Public API’ye Giriş

Zapier, Make, n8n ve yazdığın her satır kod — hepsi tek bir API’nin üzerinde durur: Purvisor Public API (v1). Panelden bir API anahtarı üretirsin, GET /me ile 30 saniyede bağlantıyı doğrularsın, ve aynı anahtarla kontak açar, arama başlatır, webhook’a abone olursun. Ayrı “Zapier API’si” yoktur; Zapier’in gördüğü uçlarla senin curl’ün gördüğü uçlar birebir aynıdır.

Kimler kullanır?

Purvisor Public API, Purvisor’ı dışarıdaki sistemlerle konuşturmanın standart yoludur. Dört tür kullanıcı hep aynı REST yüzeyine bağlanır:

Bir “no-code” aracıyla mı yoksa kendi kodunla mı bağlanacağın fark etmez — bu sayfadaki her şey dördü için de geçerlidir.

Temel URL

Tüm uçlar tek bir kök adres altında toplanır:

https://app.purvisor.ai/api/v1

Yerel geliştirme veya test yaparken temel URL, ortamının NEXTAUTH_URL değerinden gelir (örn. http://localhost:3000 ya da bir ngrok tüneli) — sonuna yine /api/v1 eklenir.

Kimlik doğrulama — tek satırlık özet

Her /api/v1/* isteği bir API anahtarı ister. Anahtar pk_live_ ön ekiyle başlar ve 48 hex karakterle devam eder (toplam 56 karakter). Tarayıcı oturumu (cookie) v1’de kullanılmaz; kimlik yalnızca anahtarla belirlenir, yani sunucu-sunucu çağrıları için birebir uygundur.

Anahtarı üç şekilde gönderebilirsin (öncelik sırasıyla):

X-API-Key: pk_live_...            ← önerilen
Authorization: Bearer pk_live_... ← alternatif
?api_key=pk_live_...              ← Zapier uyumluluğu için query

Anahtar geçersizse her uç aynı yanıtı verir: HTTP 401 + {"error":"invalid_api_key"}. Anahtarı nasıl oluşturacağın, sakladığın ve döndürdüğün ayrı bir sayfada: Kimlik Doğrulama.

JSON kuralları

Purvisor Public API sade JSON konuşur, ama üç noktayı bilmek ilk saatte yaşayacağın kafa karışıklığını önler.

1. Yanıt şekli uca göre değişir

Bazı uçlar çıplak bir dizi ([...]) döner, bazıları {data:[...]} sarmalar. Kural, ucun amacına bağlıdır:

Arama/liste uçlarının çıplak dizi dönmesi Zapier’in “search” aksiyonlarının beklentisidir: sonuç bulunamazsa boş dizi döner (404 değil). Kodunda if (!results.length) ile “eşleşme yok” durumunu ele al.

2. ID’ler string’dir

Kullanıcı, kontak, telefon numarası ve webhook aboneliği kimlikleri veritabanında BigInt’tir; JSON sayı sınırını aşmamak için yanıtlarda string olarak serileştirilir. Asistan kimliği zaten string’dir. Kısacası: ID’leri her zaman metin gibi taşı, sayıya çevirme.

{ "id": "1042", "email": "info@ornek.com", "name": "Ahmet Yılmaz" }

3. İstek gövdesi snake_case VEYA camelCase kabul eder

Kontak ve arama uçlarında alan adlarını iki biçimde de yazabilirsin; ikisi de çalışır. first_name ile firstName, phone_number_id ile phoneNumberId aynı anlama gelir. Otomasyon aracın hangisini üretiyorsa onu gönder, dönüştürmekle uğraşma.

30 saniyede ilk istek: GET /me

En hızlı “merhaba” — anahtarının çalıştığını kanıtlayan tek çağrı. Zapier ve Make de bağlantıyı bununla test eder.

curl https://app.purvisor.ai/api/v1/me \
  -H "X-API-Key: pk_live_YOUR_KEY_HERE"

{
  "id": "1042",
  "email": "info@ornek.com",
  "name": "Ahmet Yılmaz"
}

{ "error": "invalid_api_key" }

📸 [Ekran görüntüsü: Ayarlar → API Anahtarı bölümü, “Anahtar Oluştur” butonu ve tek seferlik anahtar kutusu]

“Ya oran sınırı (rate limit)?”

/api/v1 uçları API anahtarı başına dakikada 60 istek ile sınırlıdır. Limit IP’ye değil anahtara bağlıdır; aşarsan HTTP 429 döner ve yanıttaki Retry-After başlığı kaç saniye bekleyeceğini söyler. Normal bir entegrasyonda bu limite pek çarpmazsın — döngü içinde çağrı yapmadığın sürece.

Asıl sert kapı arama başlatmadadır: dakika bakiyen 1’in altındaysa POST /calls çağrısı HTTP 402 + {"error":"Insufficient minute balance"} döner. Tüm hata kodlarının tablosu: Limitler ve Hatalar.

Sırada ne var?

Bağlantın çalışıyorsa, sıra gerçek işi yapan uçlarda:

İlgili