Kendi sisteminizle veri alışverişi: randevu, webhook ve entegrasyonlar
Kendi yazılımınızla KuleConnect arasında hangi yönde hangi verinin taşınabildiğini; randevu gönderme ucunu, anket sonucu ve sohbet akışı webhook'larını anlatır.
KuleConnect ile kendi yazılımınız arasında veri dört yoldan taşınır. Bu yazı her yolun ne işe yaradığını ve geliştiricinizin bilmesi gerekenleri özetler.
| Yön | Yol | Ne için? |
|---|---|---|
| KuleConnect sizin API'nizden çeker | Firma Entegrasyonlarım | Müşteri, randevu ve hizmetlerin düzenli eşitlenmesi |
| Siz KuleConnect'e gönderirsiniz | POST /v1/integrations/appointments | Gerçekleşen randevulara anket daveti |
| KuleConnect size gönderir | Anket sonucu webhook'u | Doldurulan anketin cevapları |
| KuleConnect size gönderir | Sohbet akışı webhook adımı | WhatsApp ve Telegram sohbetinde toplanan cevaplar |
Müşteri oluşturuldu, sipariş geldi gibi genel olaylara abone olunan bir webhook ekranı henüz yok. Uygulamalar menüsündeki API ve Webhook kısayolu API Anahtarları sayfasını açar.
Firma Entegrasyonlarım (çekme)
Müşteri ve randevularınız başka bir programdaysa KuleConnect bunları sizin API'nizden belirlediğiniz aralıkla çeker. Kurulum, alan eşleştirme ve sisteminizin sunması gereken uçlar ayrı yazıda: Firma Entegrasyonlarım: kendi yazılımınızdan veri çekme.
Randevu göndermek (anket davetleri için)
Randevu yazılımınız gerçekleşen randevuları KuleConnect'e gönderirse müşteriye otomatik memnuniyet anketi daveti gider. Anahtar ve imza: API'ye genel bakış ve kimlik doğrulama.
POST https://panel.ornek.com/v1/integrations/appointments gövdesinde appointments dizisi gönderilir; tek istekte en fazla 500 randevu. Her randevunun alanları:
| Alan | Zorunlu | Açıklama |
|---|---|---|
external_id | Önerilir | Sizin randevu kimliğiniz. Aynı kimlik yeniden gelirse kayıt güncellenir. |
customer.full_name | Evet | Müşterinin adı soyadı. customer içinde phone, email ve external_id de gönderilebilir. |
services | Evet | En az bir hizmet; her biri name (zorunlu) ve isteğe bağlı external_id. |
starts_at, ends_at | Evet | ISO 8601 zaman. Yerine start_date + start_time ve end_date + end_time de olur. |
status | Hayır | scheduled, confirmed, in_progress, completed, cancelled ya da no_show. |
staff.full_name, location, notes | Hayır | Personel, şube ve not. |
Kendi durum kodlarınızı kullanıyorsanız (ör. 1 = tamamlandı) bunları Anket entegrasyonu sayfasında kaynağın Durum eşlemesi (JSON, isteğe bağlı) alanında eşleyin: {"1": "completed"}.
Yanıt kaç randevunun eklendiğini, güncellendiğini ve atlandığını döndürür: {"success": true, "accepted": 3, "updated": 1, "skipped": 1, "errors": [{"external_id": "…", "message": "customer.full_name zorunlu."}]}. Hatalı satır diğerlerini durdurmaz.
Tek randevunun durumunu sormak için GET /v1/integrations/appointments/{external_id}: randevu durumu ile anketin doldurulup doldurulmadığı (survey.completed, survey.completed_at) döner.
Anket sonucu webhook'u
Kaynağın Sonuç geri bildirimi (callback URL) alanına bir adres yazarsanız, müşteri anketi doldurduğunda cevaplar o adrese POST edilir.
- Başlıklar:
X-KuleConnect-Event(survey.completed),X-KuleConnect-Event-Id,X-KuleConnect-TimestampveX-KuleConnect-Signature. İmza, API isteklerindekiyle aynı yöntemle ve aynı gizli anahtarla hesaplanır; gelen isteği aynı kodla doğrulayabilirsiniz. - Gövde:
event; randevu bilgileri (appointment.external_id,customer_external_id,customer_name,starts_at,ends_at); anket (survey.id,survey.title); cevaplar (response.completed_atve her soru içinquestion,type,value). - Yeniden deneme: Adresiniz 2xx dışında bir kodla yanıt verirse ya da ulaşılamazsa bildirim 1, 5, 30, 120 ve 720 dakika sonra yeniden denenir; sonra bırakılır. Aynı bildirimi iki kez işlememek için
X-KuleConnect-Event-Iddeğerini saklayın.
Sohbet akışında webhook adımı
WhatsApp ya da Telegram sohbet akışında topladığınız cevapları kendi sisteminize göndermek için akışa bir İşlem adımı ekleyip işlem olarak Dış sisteme gönder (webhook) seçin ve adresinizi yazın. Adres https:// ile başlamalıdır. Akış kurulumu: Sohbet akışları.
- Gövde:
flow(akış adı),channel,conversation_id,customer_id,contactvevariables(akışta toplanan cevaplar). - İmza:
X-KuleConnect-TimestampveX-KuleConnect-Signaturebaşlıkları gelir. Bu imzanın anahtarı API gizli anahtarı değildir; akış düzenleme ekranında Webhook imza anahtarı olarak yazar. - Yanıtla değişken döndürmek: Yanıtınızda
{"variables": {"bakiye": "1250"}}gibi bir nesne döndürürseniz bu değerler akış değişkenlerine eklenir ve sonraki adımlarda{bakiye}olarak kullanılabilir. - Adresiniz 10 saniye içinde 2xx koduyla yanıt vermelidir. Bu adımda yeniden deneme yoktur; adresinize ulaşılamazsa ya da 2xx dışında bir kod dönerse (ör.
500) sohbete “Akış işlemi başarısız: Webhook 500 yanıtı döndü (adres)” gibi bir ekip notu düşer ve akış sonraki adımla sürer. Hatalı yanıttaki değişkenler akışa eklenmez.