Piyzi API: kendi sisteminizi Piyzi'ye bağlama

Piyzi API, kendi web sitenizi, formunuzu ya da kullandığınız başka bir yazılımı Piyzi'ye bağlamanızı sağlar: dışarıdan gelen talepler Piyzi'de müşteri kaydına ve randevuya dönüşür. Modülü Pi Store'dan açar, Geliştirici Araçları sayfasından bir API anahtarı oluşturur ve anahtarı sisteminizi geliştiren kişiye teslim edersiniz. Bu işlemler yalnız web panelinden yapılır.

Ne işe yarar?

• Web sitenizdeki randevu ya da iletişim formundan gelen kişiyi elle uğraşmadan müşteri kaydına dönüştürme.

• Hizmet listenizi ve bir personelin belirli bir gündeki boş saatlerini dışarıdan sorgulama.

• Tek istekle randevu oluşturma: müşteri telefon numarasından bulunur ya da oluşturulur, randevu ve adisyon Piyzi'de açılır.

• Müşteri kaynağı (nereden geldi) ve etiket tanımlarını okuma, gerekirse yeni tanım ekleme.

• Adres alanları için ülke, il ve ilçe listelerini çekme.

• WhatsApp: onaylı mesaj şablonlarını listeleme, şablonla (başlığında görsel, video ya da PDF olan ve adlı değişken kullanan şablonlar dahil) ya da (24 saatlik yanıt penceresi açıkken) serbest metinle mesaj gönderme, ileri tarihe planlama, planlanan gönderimi iptal etme ve mesaj eklerini indirme (WhatsApp Business entegrasyonu bağlıysa).

• Webhook: gelen WhatsApp mesajlarını, giden mesajları ve başarısız planlı gönderimleri kendi sisteminize anlık olay bildirimi olarak alma — kendi gelen kutunuzu kurabilirsiniz.

İstekleri iki yönde de akıtabilirsiniz: uçlara siz sorarsınız, Piyzi yanıtlar; webhook tanımlarsanız gelen/giden WhatsApp mesajları da anlık olarak sizin sisteminize iletilir.

Ön koşullar

• Aboneliği aktif bir Piyzi hesabı.

• Modülü açıp kapatmak için rolünüzde Entegrasyonları yapabilir yetkisi (işletme sahibi her zaman yapabilir).

• Geliştirici Araçları sayfasını görmek için Piyzi API anahtarlarını ve geliştirici araçlarını görebilir yetkisi; anahtar ve webhook oluşturmak, düzenlemek, yenilemek ve silmek için Piyzi API anahtarlarını yönetebilir (oluşturma/silme/yenileme) yetkisi. Yalnız görüntüleme yetkisi olan kullanıcı düğmeleri görür ama işlem “Bu işlemi yapmaya yetkiniz yok.” uyarısıyla reddedilir.

• İstekleri gönderecek sunucunun sabit bir çıkış IP adresi (önerilen). Sabit IP veremeyen altyapılar için anahtar bazında IP kısıtı olmadan kullanım seçeneği vardır (aşağıda).

• İstekleri yazacak bir geliştirici. Anahtar tarayıcıda değil, yalnız sunucu tarafında kullanılır.

Modülü açma

1. 1

   Piyzi API penceresini açın

   Sol menüden İşletmem → Pi Store sayfasını açın ve Özel Modüller başlığı altındaki Piyzi API kartına tıklayın.

2. 2

   Aktifleştirin

   Pencerede Aktifleştir düğmesine basın. Sayfa hemen yenilendiği için ekranda ayrı bir başarı mesajı görmeyebilirsiniz; modülün açıldığını kartta Bağlı rozetinden anlarsınız.

3. 3

   Geliştirici Araçları'na geçin

   Sol menüde İşletmem altında Geliştirici Araçları belirir. Piyzi API penceresini yeniden açtığınızda Geliştirici Araçları'na Git düğmesi de sizi oraya götürür.

API anahtarı oluşturma

1. 1

   Yeni anahtar penceresini açın

   İşletmem → Geliştirici Araçları sayfasını açın. API Anahtarları sekmesinde sağ üstteki Anahtar Oluştur düğmesine basın (henüz anahtar yoksa ortadaki aynı düğmeyi de kullanabilirsiniz). Yeni API Anahtarı penceresi açılır.

2. 2

   Ad verin

   Anahtar Adı alanına anahtarı nerede kullanacağınızı anlatan bir ad yazın (örneğin “Web Sitesi Formu”); ad 2–60 karakter olmalıdır.

3. 3

   IP kısıtlamasını seçin

   IP kısıtlaması altında varsayılan olarak IP listesiyle sınırla (önerilen) seçilidir. İzinli IP Adresleri alanına sunucunuzun çıkış IP adresini yazın; başka adres eklemek için IP Ekle düğmesine basın. Sabit çıkış IP'si veremiyorsanız IP kısıtı olmadan kullan (sunucusuz altyapılar için) seçeneğini işaretleyip “Riski anladım, bu anahtar IP kısıtı olmadan kullanılsın.” kutusunu onaylayın; bu modda IP listesi istenmez.

4. 4

   Oluşturun ve anahtarı kopyalayın

   Oluştur düğmesine basın. API Anahtarınız Hazır penceresi açılır: anahtarı yanındaki kopyala simgesiyle kopyalayıp güvenli bir yere kaydedin, sonra Kopyaladım, Kapat düğmesine basın.

• “Anahtar adı en az 2 karakter olmalıdır.”: ad çok kısa.

• “En az bir IP adresi girmelisiniz.” ya da “En az bir geçerli IP adresi girmelisiniz.”: IP listesi modunda adres yok ya da biçimi geçersiz (örneğin 203.0.113.10 biçiminde yazın).

• “Devam etmek için riski anladığınızı onaylayın.”: IP kısıtı olmadan kullanım seçiliyken onay kutusu işaretlenmemiş.

• “API anahtarı limitine ulaşıldı (en fazla 5 anahtar).”: kullanmadığınız bir anahtarı silip yeniden deneyin.

Bir işletme en fazla 5 anahtar tutabilir. Her sistem için ayrı anahtar oluşturmak iyi bir alışkanlıktır: biri sızdığında yalnızca o anahtarı yenilersiniz, diğer entegrasyonlarınız çalışmaya devam eder.

IP izin listesi — ikinci savunma hattı

Anahtar kimliği doğrular; IP listesi ise anahtarın nereden kullanılabileceğini sınırlar. Anahtar başkasının eline geçse bile listede olmayan bir sunucudan gelen istek reddedilir.

• Varsayılan mod IP listesidir; bir anahtara en fazla 20 adres eklenebilir.

• Sabit çıkış IP'si veremeyen altyapılar (Cloudflare Workers, Vercel, AWS Lambda gibi) için anahtar bazında “IP kısıtı olmadan kullan” modu vardır. Bu mod, anahtarı oluştururken ya da düzenlerken riski kabul eden bir onay kutusuyla seçilir ve listede “IP kısıtsız” rozetiyle görünür. Hız sınırları ve kaba kuvvet koruması bu modda da aynen devrededir.

• Listeye sunucunuzun çıkış (egress) IP adresini yazın — ziyaretçinin ya da ofisinizin IP'sini değil.

• Listede olmayan bir adresten gelen istek 403 IP_NOT_ALLOWED ile döner ve yanıttaki mesaj hangi IP'nin görüldüğünü söyler; sunucunuzun gerçek çıkış adresini bu şekilde öğrenebilirsiniz.

• Sunucunuzun IP'si değişirse (barındırma değişikliği, yeni sunucu) listeyi güncelleyin; anahtarı yenilemeniz gerekmez.

Anahtarı yenileme, kapatma ve silme

Anahtar listesinde her anahtarın adı, ilk karakterleri, izinli IP'leri, Son Kullanım ve Aktif sütunları ile satır sonunda düzenle (kalem), Anahtarı Yenile (dairesel ok) ve Sil (çöp kutusu) simgeleri bulunur.

• Yenileme: Anahtarı Yenile simgesine basıp “Anahtar yenilensin mi?” sorusunu Evet, Yenile ile onaylayın. Yeni anahtar API Anahtarınız Hazır penceresinde bir kez gösterilir; eski anahtar aynı anda geçersiz olur. Pasife alınmış bir anahtarı yenilemek onu yeniden açar. Anahtarın sızdığından şüpheleniyorsanız ilk yapılacak budur.

• Pasife alma: Aktif sütunundaki anahtarı kapattığınızda o anahtarla gelen istekler hemen reddedilir. Anahtar silinmez; yeniden açtığınızda aynı değerle çalışır.

• Silme: çöp kutusuna basıp “Anahtar silinsin mi?” sorusunu Evet, Sil ile onaylayın; anahtar kaldırılır ve o anahtarla yapılan istekler anında durur. Silinen anahtar geri getirilemez ve 5 anahtar sınırından düşer.

• Düzenleme: kalem simgesi Anahtarı Düzenle penceresini açar; adı, IP listesini ve IP kısıtlaması modunu değiştirip Kaydet düğmesine basarsınız. Anahtarın değeri değişmez.

• Son Kullanım sütunu, anahtarla en son ne zaman kabul edilen bir istek yapıldığını gösterir; bir bitiş tarihi değildir, anahtarların süresi dolmaz. Hiç kullanılmamış anahtarda “-” yazar. Hangi anahtarın gerçekten kullanıldığını buradan anlarsınız.

Webhook ile olayları alma

Geliştirici Araçları sayfasındaki Webhook sekmesinden bir HTTPS adresi tanımlarsınız; Piyzi, WhatsApp mesaj olaylarını bu adrese imzalı POST istekleri olarak gönderir. Böylece işletmenizin gelen kutusunu kendi yazılımınızda kurabilir, müşteriye kendi ekranınızdan cevap yazabilirsiniz (yanıt penceresi açıkken serbest metin, her zaman onaylı şablon). İşletme başına bir webhook tanımlanır.

1. 1

   Ucu hazırlatın

   Geliştiriciniz, Dokümantasyon sekmesindeki Webhook'lar sayfasına göre bir uç hazırlar. Kayıt sırasında Piyzi bu adrese challenge parametresi taşıyan bir GET isteği gönderir; uç 2xx durum koduyla dönüp challenge değerini düz metin olarak aynen yazmalıdır.

2. 2

   Adresi kaydedin

   Webhook sekmesinde Webhook Tanımla düğmesine basın. Webhook URL alanına herkese açık bir HTTPS adresi yazın (443 portu; IP adresi ve özel ağ adresleri kabul edilmez). Gönderilecek olaylar altındaki Gelen mesaj, Giden mesaj ve Başarısız gönderim seçenekleri baştan işaretli gelir; almak istemediklerinizin işaretini kaldırın (en az biri işaretli kalmalıdır) ve Kaydet düğmesine basın. Doğrulama başarılıysa “Webhook oluşturuldu ve doğrulandı.” mesajı çıkar; uç hazır değilse kayıt tamamlanmaz.

3. 3

   İmza anahtarını saklayın

   Webhook imza anahtarınız penceresinde anahtar yalnız bir kez gösterilir. Kopyalayıp geliştiricinize güvenli bir kanaldan iletin, sonra Anahtarı kaydettim, kapat düğmesine basın. Geliştiriciniz her isteğin X-Piyzi-Signature başlığını bu anahtarla (HMAC-SHA256) doğrular.

4. 4

   Test edin ve izleyin

   Test Gönder ile örnek bir olay yollayın; sonuç kartın altında görünür. Gönderimlerin gidişatını Son Teslimatlar tablosundan izleyin; her teslimatın zamanı, olayı, deneme sırası, sonucu ve süresi burada görünür.

• Düzenle ile adresi ya da olayları değiştirirsiniz; adres değişirse doğrulama yeniden yapılır.

• Duraklat gönderimi durdurur; Aktifleştir adresi yeniden doğrulayıp gönderimi açar. Webhook duraklatılmış ya da durdurulmuşken oluşan olaylar sonradan gönderilmez.

• Anahtarı Yenile imza anahtarını değiştirir; eski anahtar anında geçersiz olur ve yeni anahtar bir kez gösterilir.

• Sil olay gönderimini durdurur; teslimat geçmişi 14 gün içinde kendiliğinden temizlenir.

• Başarısız bir teslimat en fazla 5 kez denenir; olayların sırası garanti edilmez.

Geliştiriciniz için teknik özet

Adres ve kimlik doğrulama

• Temel adres: https://api.piyzi.com/api/v1

• Kimlik: her istekte X-Api-Key başlığı (X-Api-Key: pyz_live_…). Alternatif olarak Authorization: Bearer pyz_live_… da kabul edilir.

• Yanıt zarfı: başarılı istekte { "success": true, "data": … }, başarısız istekte { "success": false, "error": { "code", "message" } }.

• Bu yüzey Piyzi panelinin API'sinden ayrı ve izoledir: panelin oturum anahtarı (JWT) burada geçerli değildir, tek kimlik API anahtarıdır. Tersi de geçerlidir — API anahtarıyla panel uçlarına erişilemez.

Kaynaklar uid ile adreslenir

Dışarıya veritabanı kimliği verilmez. Hizmet, personel, müşteri, randevu, müşteri kaynağı ve konum kayıtlarının hepsi uid alanıyla taşınır: serviceUid, staffUid, customerUid, appointmentUid, sourceUid, countryUid, cityUid, districtUid. Etiketler ise uid yerine başlıklarıyla (title) gönderilir. Bir kimliği elle uydurmayın ya da başka bir yerden kopyalamayın; ilgili listeleme ucundan okuyun.

Sınırlar

• Anahtar başına dakikada 120 istek.

• Yazma (POST) uçlarında ek sınır: dakikada 30 ve günde 2.000 istek.

• Başarısız anahtar denemeleri: IP başına dakikada 20.

• İstek gövdesi en fazla 200 KB.

• Sınır aşımında 429, gövde çok büyükse 413, gövde geçerli JSON değilse 400 INVALID_JSON döner; istek sıklığını azaltıp ya da gövdeyi düzeltip yeniden deneyin.

Uç listesi ve kod örnekleri nerede?

Tam referans uygulamanın içindedir: İşletmem → Geliştirici Araçları → Dokümantasyon. Orada her uç için parametre tabloları, örnek yanıtlar, uçların dönebileceği kodların listesi ve cURL / JavaScript / PHP / Python örnekleri bulunur. Aynı sayfadaki Postman Collection'ı İndir düğmesiyle Postman koleksiyonunu da indirebilirsiniz.

• Bağlantı testi: GET /me — anahtarın hangi işletmeye ait olduğunu döner.

• Tanımlar: müşteri kaynakları, etiketler ve ülke / il / ilçe listeleri.

• Randevu akışı: hizmetler, boş saatler, müşteri oluşturma ve randevu oluşturma.

Randevu API ile oluşturulduğunda ne olur?

• Müşteri telefon numarasından eşleştirilir: kayıt varsa aynı müşteriye yazılır, yoksa yeni müşteri açılır. Böylece form her doldurulduğunda mükerrer kayıt oluşmaz.

• Yalnız Türkiye cep telefonu numaraları (5 ile başlayan 10 hane) kabul edilir; 05xx, 5xx, 90 ya da +90 ile başlayan yazımlar tek biçime çevrilir. Geçersiz numara 400 INVALID_PHONE ile döner.

• Randevu “Bekliyor” durumunda oluşur ve kaynağı API olarak işaretlenir.

• İşletmem → Ayarlar → Randevu Ayarları'nda “Online Randevu Otomatik Onay” açıksa randevu onaylı gelir; kapalıysa üst çubuktaki Onay Bekleyenler panelinin Randevu Talepleri sekmesine düşer.

• Randevu için müşterinin o güne ait açık adisyonu kullanılır; yoksa yeni adisyon açılır.

• Piyzi bu randevu için müşteriye kendiliğinden SMS göndermez. Haber vermek isterseniz “Randevu Oluşturulduğunda” tetikleyicili bir otomasyon kurun; bu otomasyon API ile gelen randevuda da çalışır. API ile açılan yeni müşteri için “Yeni Müşteri Kaydı Olduğunda” otomasyonu çalışmaz.

• Seçilen saat bu arada dolduysa istek 409 TIME_SLOT_CONFLICT ile reddedilir; güncel saatler yeniden sorgulanıp tekrar denenmelidir. Geçmiş bir saat 400 DATE_IN_PAST ile reddedilir.

Modülü kapatma

1. 1

   Piyzi API penceresini açın

   İşletmem → Pi Store sayfasında Piyzi API kartına tıklayın.

2. 2

   Devre dışı bırakın

   Devre Dışı Bırak düğmesine basın ve “Piyzi API devre dışı bırakılsın mı?” sorusunu Evet, Devre Dışı Bırak ile onaylayın.

• Tüm API istekleri 403 INTEGRATION_DISABLED ile reddedilir.

• Geliştirici Araçları sayfası menüden kalkar.

• Anahtarlarınız silinmez; modülü yeniden açtığınızda aynı anahtarlar çalışmaya devam eder.

• Daha önce API ile oluşmuş müşteri ve randevular Piyzi'de olduğu gibi kalır.

• Tanımlı bir webhook, modülü kapatınca durmaz. Olay gönderimini de kesmek istiyorsanız modülü kapatmadan önce Webhook sekmesinde webhook'u Duraklat ile durdurun ya da silin.

Sorun giderme

• 401 MISSING_API_KEY: istek anahtar başlığı olmadan gönderilmiş ya da gönderilen değer bir Piyzi anahtarı biçiminde değil.

• 401 INVALID_API_KEY: anahtar yanlış, silinmiş, pasife alınmış ya da yenilendiği için eski kalmış.

• 403 IP_NOT_ALLOWED: isteğin geldiği IP anahtarın listesinde değil. Yanıttaki mesajda görünen adresi listeye ekleyin.

• 403 INTEGRATION_DISABLED: Piyzi API modülü Pi Store'da kapalı; açın.

• 429 döndü: sınır aşıldı. Genel istek, dakikalık yazma, günlük yazma ve başarısız anahtar denemesi sınırları ayrı ayrı işler; yanıttaki code alanı hangisinin dolduğunu söyler.

• 404 NOT_FOUND: adres yanlış yazılmış. Geçerli uçların listesi Dokümantasyon sekmesindedir.

• Webhook kaydedilemiyor: “Webhook doğrulaması başarısız” uyarısı ucun GET isteğine 2xx dönüp challenge değerini aynen yazmadığını, “Webhook URL'i geçersiz” uyarısı adresin herkese açık bir HTTPS adresi olmadığını gösterir.

• Randevu görünmüyor: istek başarılı dönüyorsa randevu büyük olasılıkla Onay Bekleyenler panelindeki Randevu Talepleri sekmesindedir; otomatik onay kapalıysa buradan onaylanır.

• Aynı kişi iki kez kaydolmuş: eşleştirme telefon numarasıyla yapılır; iki kayıt farklı numaralarla açılmış demektir.