Yazılımcılar için

Kendi rezervasyon sisteminizi bağlayın

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ı POST istekleri 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):

  1. 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.
  2. 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):

  1. İş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.
  2. 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.
  3. 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):

  1. İş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).
  2. 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.
  3. 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:

  1. 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.
  2. 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_services cevabında personel listesi gönderirseniz asistan müşteriye personel seçtirir ve isteği staff_id ile gönderir.
  3. 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.
  4. 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ş saatler
  • createBooking($pdo, $b): randevuyu verilen $pdo işleminde yazar
  • cancelBooking($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ı:

  1. blinkerbot-booking.php dosyası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.
  2. Uç dosyasını oluşturun (ör. blinkerbot-endpoint.php) ve 4 fonksiyonu yazın.
  3. İş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
  4. 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ız capabilities: ["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ı note ve replaces_booking_id. idempotency_key zorunlu. 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_key ikinci kez gelirse yeni kayıt açmayın, ilk cevabı dönün.
  • Aynı anahtar farklı içerikle gelirse idempotency_mismatch dö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; +0300 biçimi kabul edilir ama Z olmadan 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 → https ya da www yö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 0600 izniyle saklayın.
  • İmzayı her istekte doğrulayın; doğrulanmamış isteğe 401 dönün.
  • Adres yalnız https ve 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.