Bu sayfa, kendi randevu sistemi olan bir işletmenin yazılımcısı içindir. Bağlantı kurulunca Blinkerbot asistanının (WhatsApp, Instagram, web sohbeti, telefon) aldığı randevular, sizin sisteminizde müşterinin adıyla gerçek kayıt olarak oluşur.
Nasıl çalışır
- Blinkerbot sizin sisteminizdeki tek bir adrese imzalı
POSTistekleri gönderir. Hangi işlem olduğu gövdede yazar. - Asıl kaynak sizin sisteminizdir. Blinkerbot'taki kayıt yalnız bir aynadır.
- Sizin bize istek atmanız gerekmez. Gizli anahtarı kimse elle taşımaz: işletme sahibi paneldeki bağlantı kodunu sizin kurulum ekranınıza yapıştırır, imza sırrı iki sistem arasında kendiliğinden kurulur.
- Sisteminiz o an cevap veremezse müşteri kaybolmaz: talep bekler, sistem dönünce işlenir, müşteriye sonuç bildirilir.
Adım adım bağlantı
İşletme sahibi panelde, yazılımcı kendi sunucusunda çalışır. Toplam iki yol var; ikisi de aynı otomatik testten geçer.
Ön koşullar (işletme sahibi):
- Panelde Ayarlar > Randevu > Kendi sistemim sekmesini açın. "Bu özellik çalışma alanınız için açık değil" yazıyorsa bize yazın; özelliği hesabınıza biz açarız.
- Bu ekrandaki her önemli adım (kod oluşturma, adresi kaydetme, bağlantıyı açma) iki adımlı doğrulama (2FA) kodu ister. Hesabınızda 2FA açık değilse önce Hesap > Güvenlik'ten açın. Güvenlik gereği 2FA'yı ya da şifreyi yeni değiştirdiyseniz bu ekran 24 saat kilitli kalır.
Yol A: bağlantı kodu (hazır paket ya da örnekler kullanılıyorsa, önerilen):
- İşletme sahibi Bağlantı kodu oluştur'a basar, 2FA kodunu girer.
blk_pair_ile başlayan kod 2 saat geçerlidir ve bir kez kullanılır. Kodu yazılımcıya iletir. - Yazılımcı kodu paketin kurulum komutuna verir (ör.
php blinkerbot-endpoint.php pair blk_pair_XXXX --url https://www.siteniz.com/blinkerbot-endpoint.php). Paket uç adresinizi bize bildirir, imza sırrını alır ve web kökünün dışındaki sır dosyasına yazar. Sır hiçbir ekranda görünmez. - Kodun süresi dolduysa ya da yanlış girildiyse yeni kod oluşturmak yeterlidir; hata mesajı güvenlik gereği her durumda aynıdır.
Yol B: elle kurulum (sözleşmeyi kendiniz uyguladıysanız):
- İşletme sahibi Elle kurulum bölümüne uç adresini (
https://, 443 portu) yazar. İmza sırrı alanıwhsec_…biçiminde rastgele üretilmiş olarak gelir; Yeni üret ile değiştirilebilir. Sisteminizde zaten bir sır varsa onu da yazabilirsiniz (whsec_+ en az 24 baytlık base64). - Adresi ve sırrı kaydet'e basıp 2FA kodunu girer. Sır bir kez gösterilir: kopyalanıp doğrudan sisteminizin ayarına yapıştırılır, e-posta ya da sohbetle gönderilmez.
- Yazılımcı aynı sırrı kendi sisteminde imza doğrulamasında kullanır (aşağıdaki İmza bölümü).
Ortak son adımlar:
- Otomatik test kendiliğinden çalışır (ya da Tekrar test et). Her adımın yanında geçti/kaldı ve nedeni yazar; adımlar Otomatik test bölümünde.
- Test geçince sisteminizdeki hizmetler gelir. Hizmetleri eşleyin: her birini Blinkerbot'taki bir hizmetle eşleyin ya da Blinkerbot'a ekleyin. Eşlenmeyen hizmet için asistan randevu almaz.
list_servicescevabında personel listesi gönderirseniz asistan müşteriye personel seçtirir ve isteğistaff_idile gönderir. - Randevuları kendi sistemime yaz > Aç (2FA). Açmak için test geçmiş ve en az bir hizmet eşlenmiş olmalıdır. Açıkken Google ve Microsoft takvimleri randevu kaynağı olmaz.
- Sistem bir an cevap veremezse talepler Onay bekleyen talepler sayfasında bekler; sistem dönünce işlenir ve müşteriye sonuç bildirilir. İşletme sahibi bağlantıyı aynı ekrandan tek tıkla kapatabilir, adresi değiştirebilir ya da sırrı yenileyebilir.
En hızlı yol: hazır PHP paketi
Tek dosya, bağımlılıksız (Composer yok), PHP 7.4–8.3, PDO (MySQL/MariaDB InnoDB veya SQLite). Paket imza doğrulamayı, bağlantı kodu kurulumunu, ping'i, tekrar korumasını, hata kodlarını, test isteklerini ve saat değişikliğini hazır getirir. Siz yalnız kendi tablolarınızı okuyan ve yazan 4 küçük fonksiyonu yazarsınız:
listServices(): hizmetler (id, ad, süre; isteğe bağlı fiyat ve personel listesi)findSlots($q): bir hizmet (ve isteğe bağlı personel) için boş saatlercreateBooking($pdo, $b): randevuyu verilen$pdoişleminde yazarcancelBooking($pdo, $id): iptal (zaten iptalse yine başarı)- isteğe bağlı
getBooking($id)
Tahmini iş: 6–20 saat. İndirin: blinkerbot-booking.php · örnek ayar dosyası · paket belgesi
Kurulum adımları:
blinkerbot-booking.phpdosyasını sunucunuza koyun, örnek ayar dosyasını kopyalayıp veritabanı bilgilerinizi yazın. Sır dosyası için web kökünün dışında bir yol seçin.- Uç dosyasını oluşturun (ör.
blinkerbot-endpoint.php) ve 4 fonksiyonu yazın. - İşletme sahibi panelde Ayarlar > Randevu > Kendi sistemim > Bağlantı kodu oluştur'a basar (kod 2 saat geçerli, tek kullanımlık). Kodu sunucuda şöyle girin (web sunucusunun kullanıcısıyla):
php blinkerbot-endpoint.php pair blk_pair_XXXX --url https://www.siteniz.com/blinkerbot-endpoint.php - Panelde otomatik test çalışır. Yeşil olunca sahip hizmetleri eşler ve bağlantıyı açar.
Node (Express) ve Python (FastAPI) için aynı 4 fonksiyon düzeninde örnekler: Node örneği · Python örneği
Yapay zekâ asistanınızla
Hazır istemi ChatGPT ya da Claude'a yapıştırın, kendi tablolarınızı anlatın; size 4 fonksiyonu yazsın. Hatalı kod müşteriye ulaşmaz: panel testi geçmeden bağlantı açılamaz. Yapay zekâ araçları için llms.txt.
Sözleşme
Tüm istekler POST {adresiniz} olarak gelir. Gövde JSON'dur: operation, request_id, idempotency_key, account, test, data.
ping: bağlantı ve imza kontrolü (paket kendisi cevaplar). Saat değişikliğini tek istekte yapabiliyorsanızcapabilities: ["replaces_booking_id"]bildirin.list_services: hizmetler. Zorunlu.find_slots:service_id, isteğe bağlıstaff_id,from,to,timezone,limit(1–500; en erken boş saatler). Zorunlu.create_booking:service_id, isteğe bağlıstaff_id,start,end,timezone,customer(ad, telefon, isteğe bağlı e-posta),channel, isteğe bağlınotevereplaces_booking_id.idempotency_keyzorunlu. Zorunlu.get_booking,cancel_booking: önerilir. Uygulamıyorsanız HTTP 200 ile{"ok":false,"error":{"code":"not_implemented"}}dönün; asla 5xx dönmeyin.
Cevap kuralları:
- Başarı: HTTP 200,
{"ok": true, "data": …} - İş hatası: HTTP 200,
{"ok": false, "error": {"code": "…"}}. Kodlar:slot_unavailable,invalid_service,invalid_staff,outside_hours,invalid_customer,booking_not_found,cancellation_not_allowed,idempotency_mismatch,request_in_progress. - İmza hatası: HTTP 401.
- Zaman aşımı, 5xx, 429, JSON olmayan cevap ve HTML sayfası "ulaşılamadı" sayılır; talep bekletilir ve tekrar denenir.
Saatler ISO 8601 ve saat farkıyla yazılır: 2026-11-20T14:00:00+03:00. Hata mesajlarınız (message) asistana hiç gitmez; yalnız işletme sahibinin gördüğü kayda kırpılarak yazılır. Sağlık sektöründe (klinik, diş, sağlık merkezi) müşteri notu hiç gönderilmez.
Tüm ayrıntılar: OpenAPI tanımı · Postman koleksiyonu
Tekrar koruması
- Aynı
idempotency_keyikinci kez gelirse yeni kayıt açmayın, ilk cevabı dönün. - Aynı anahtar farklı içerikle gelirse
idempotency_mismatchdönün. - Anahtarı randevu kaydıyla aynı veritabanı işleminde yazın ve en az 7 gün saklayın.
- Cevabı bize ulaşmayan bir oluşturma isteğini aynı anahtarla tekrar göndeririz; çift kayıt oluşmamalıdır.
İmza (Standard Webhooks)
Her istek Standard Webhooks biçiminde imzalanır: webhook-id, webhook-timestamp, webhook-signature (v1,<base64>). İmzalanan içerik webhook-id.webhook-timestamp.ham_gövde, anahtar whsec_ önekinden sonraki base64'ün çözülmüş baytlarıdır. Zaman damgasını 5 dakika toleransla kontrol edin, imzayı sabit sürede karşılaştırın, gövdeyi doğrulamadan önce değiştirmeyin. Sır yenilenirken iki imza boşlukla ayrılmış gelir; biri tutarsa geçerlidir.
$id = $_SERVER['HTTP_WEBHOOK_ID']; $ts = $_SERVER['HTTP_WEBHOOK_TIMESTAMP'];
$body = file_get_contents('php://input');
$key = base64_decode(substr($secret, strlen('whsec_')));
$expected = 'v1,' . base64_encode(hash_hmac('sha256', "$id.$ts.$body", $key, true));
$valid = abs(time() - (int) $ts) <= 300 && in_array(true, array_map(fn($s) => hash_equals($expected, $s), explode(' ', $_SERVER['HTTP_WEBHOOK_SIGNATURE'])), true);Hazır kütüphaneler: Node npm install standardwebhooks, Python pip install standardwebhooks, PHP 8 composer require standard-webhooks/standard-webhooks.
Süre sınırları
- Telefon: boş saat 2,5 sn; oluşturma, iptal ve sorgulama 3,5 sn.
- Sohbet: boş saat 5 sn; oluşturma, iptal ve sorgulama 8 sn.
- Hizmet listesi ve ping: 5 sn.
- Cevap en çok 64 KB olabilir. Yönlendirmeler izlenmez.
Otomatik test
Bağlantı kurulunca panel şu adımları dener: ping; imza doğrulaması (yanlış imza, 10 dakika eski zaman damgası ve başka sırla imzalanmış istek 401 almalı); hizmet listesi; 7 günlük boş saatler; test: true ile deneme randevusu (kalıcı yazılmamalı); aynı anahtarla aynı randevu; farklı içerikle idempotency_mismatch; varsa sorgulama ve iptal; telefon için hız.
Sorun giderme
- Güvenlik duvarı engelliyor (403): Cloudflare Bot Fight Mode, Wordfence ya da ModSecurity istekleri engelliyor olabilir. Bu adres için istisna ekleyin. Çıkış IP'mizi yayınlamıyoruz; gerekirse bize yazın.
- 200 ile HTML dönüyor: önbellek eklentisi, bakım modu ya da giriş yönlendirmesi araya giriyor. Adresi önbellekten hariç tutun.
- İmza tutmuyor (401): gövde doğrulamadan önce yeniden kodlanıyor ya da sunucu saati kaymış. Ham gövdeyi kullanın, NTP'yi açın.
- Saatler kayık: saat farkını (
+03:00) yazdığınızdan emin olun;+0300biçimi kabul edilir amaZolmadan yerel saat kabul edilmez. - Çok yavaş: ucuz hostinglerde PHP soğuk başlayabilir. Bağlantı açıkken her 5 dakikada bir ping göndeririz.
- Yönlendirme:
http→httpsya dawwwyönlendirmesi varsa son adresi girin.
Yerel geliştirme
Bilgisayarınızdaki koda bizden istek alabilmek için bir tünel kullanın: Cloudflare Tunnel ya da ngrok. Tünelin verdiği https:// adresini bağlantı kodu kurulumunda kullanın; iş bitince gerçek adresle yeniden eşleştirin.
Güvenlik
- Sırrı kodun içine, sürüm kontrolüne ya da sohbete yazmayın; web kökünün dışındaki bir dosyada
0600izniyle saklayın. - İmzayı her istekte doğrulayın; doğrulanmamış isteğe 401 dönün.
- Adres yalnız
httpsve 443 portuyla kabul edilir. İç ağ adresleri reddedilir. - Sızıntı şüphesinde işletme sahibi bağlantıyı panelden tek tıkla kapatabilir ve sırrı yenileyebilir.
CRM otomasyonları için genel API ve imzalı webhook rehberlerine bakın. Tüm geliştirici rehberleri.