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.

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.

İstekleri her zaman sizin sisteminiz başlatır: Piyzi'ye siz sorarsınız, Piyzi yanıtlar. Piyzi'de bir şey değiştiğinde kendiliğinden sizin sisteminize haber gönderilmez; güncel bilgiye ihtiyaç duyduğunuzda ilgili ucu yeniden sorgulamanız gerekir.

Ön koşullar

• Aboneliği aktif bir Piyzi hesabı.

• Pi Store düzenleme yetkisi ya da işletme sahibi olmanız — modülü açmak için.

• Piyzi API anahtarlarını yönetebilir yetkisi — anahtar oluşturmak, yenilemek ve silmek için. Yalnız görüntüleme yetkisi olan kullanıcı sayfayı görür ama anahtar üretemez.

• İstekleri gönderecek sunucunun sabit bir çıkış IP adresi. Anahtarın IP listesi zorunludur.

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

Modülü açma

1. Sol menüden İşletmem → Pi Store bölümünü açın.

2. Özel Modüller altındaki Piyzi API kartına tıklayın.

3. Açılan pencerede “Aktifleştir” düğmesine basın.

4. İşletmem menüsünde Geliştirici Araçları sayfası görünür hale gelir.

API anahtarı oluşturma

1. İşletmem → Geliştirici Araçları sayfasını açın.

2. API Anahtarları sekmesinde “Anahtar Oluştur” düğmesine basın.

3. Anahtara onu nerede kullanacağınızı anlatan bir ad verin (örneğin “Web Sitesi Formu”).

4. İzinli IP adreslerini girin; en az bir adres zorunludur.

5. Kaydedin. Anahtar ekranda bir kez gösterilir; kopyalayıp güvenli bir yere kaydedin.

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.

• IP listesi zorunludur, boş bırakılamaz. Bir anahtara en fazla 20 adres eklenebilir.

• 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 hata 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.

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ıda { "success": true, "data": … }, hatada { "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, kaynak 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 döner; istek sıklığını azaltıp 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, hata kodu listesi ve cURL / JavaScript / PHP / Python örnekleri bulunur. Aynı sayfadan 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.

• Telefon numarasının 05xx, 5xx ya da +90 ile başlayan yazımları kabul edilir ve tek biçime çevrilir.

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

• Randevu ayarlarınızda online randevuların otomatik onayı açıksa randevu onaylı gelir; kapalıysa Bekleyen Onaylar listesine düşer.

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

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

Anahtarı yenileme, kapatma ve silme

• Yenileme: yeni anahtar üretilir ve bir kez gösterilir; eski anahtar aynı anda geçersiz olur. Anahtarın sızdığından şüpheleniyorsanız ilk yapılacak budur.

• Pasife alma: satırdaki anahtarı kapattığınızda istekler hemen reddedilir. Anahtar silinmez; dilediğinizde yeniden açabilirsiniz.

• Silme: anahtar kaldırılır ve o anahtarla yapılan istekler anında durur.

• Düzenleme: anahtarın adını ve IP listesini istediğiniz zaman güncelleyebilirsiniz; anahtarın kendisi değişmez.

• Listede her anahtarın son kullanım tarihi görünür — hangi anahtarın gerçekten kullanıldığını buradan anlarsınız.

Modülü kapatma

1. İşletmem → Pi Store bölümünü açın.

2. Piyzi API kartına tıklayın.

3. “Devre Dışı Bırak” düğmesine bası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.

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. Hata mesajındaki 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 hatalı anahtar denemesi sınırları ayrı ayrı işler; hata kodu hangisinin dolduğunu söyler.

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

• Randevu düşmüyor: istek başarılı dönüyorsa randevu büyük olasılıkla Bekleyen Onaylar listesindedir; 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.