KuleConnect API'sine genel bakış ve kimlik doğrulama

3 dakikalık okuma · Güncelleme: 23 Ekim 2026

API anahtarını nereden alacağınızı, her isteğe hangi başlıkları ekleyeceğinizi, imzanın nasıl hesaplandığını ve hata kodlarının anlamını anlatır.

KuleConnect API'si, kendi yazılımınızın (CRM, ERP, web siteniz ya da mobil uygulamanız) panele bağlanıp iş yaptırmasını sağlar. Bu yazı bütün uçlarda ortak olan kimlik doğrulamayı anlatır. Örneklerde panel adresi olarak https://panel.ornek.com kullanıyoruz; siz kendi panel adresinizi yazın.

Hangi uçlar var?

Yöntem ve adres	Ne yapar?	Dakikada en fazla
`POST /v1/integrations/ping`	Anahtar ve imzayı sınar	60
`POST /v1/integrations/appointments`	Randevu gönderir (anket davetleri için)	60
`GET /v1/integrations/appointments/{external_id}`	Randevunun anket durumunu sorar	60
`GET /v1/santral/calls`	Çağrı listesi	120
`GET /v1/santral/calls/{id}`	Tek çağrının ayrıntısı	120
`POST /v1/santral/calls`	Arama başlatır	120
`POST /v1/whatsapp/otp`	WhatsApp ile doğrulama kodu gönderir	120
`POST /v1/telegram/otp`	Telegram ile doğrulama kodu gönderir	120

Sınır aşılırsa istek 429 koduyla reddedilir; bir dakika bekleyip yeniden deneyin.

API anahtarını almak

Anahtar çifti Yönet → API Anahtarları sayfasında üretilir. Sayfa hiçbir modüle bağlı değildir; Anketler modülü paketinizde olmasa da santral ve doğrulama kodu API'si için anahtar alabilirsiniz. Sayfayı açmak için firma ayarlarını düzenleme yetkiniz olmalı.

Sağ üstteki Yeni anahtar düğmesine basın.
Anahtar adı alanına anahtarı kullanacak sistemin adını yazın (ör. “CRM”).
Oluştur ve anahtar üret'e basın.
Sayfanın üstünde çıkan sarı kutudaki iki değeri hemen kopyalayın: X-KuleConnect-Key (açık kimlik, kc_ ile başlar) ve Secret (gizli anahtar).

Dikkat: Gizli anahtar yalnız bu anda bir kez gösterilir. Kaybederseniz anahtarın kartındaki Anahtarı yenile ile yenisini üretin; eski gizli anahtar o an çalışmaz olur. Açık kimlik kartta API anahtarı (açık kimlik) olarak her zaman görünür.

Anahtar firmanızı tanıtır; aynı anahtarla santral, doğrulama kodu ve randevu entegrasyonu uçlarını kullanırsınız. Sayfanın altındaki Uçlar ve imza kartında bu uçların adresleri listelenir. Anahtarı Kapat düğmesiyle kapatırsanız o anahtarla gelen bütün istekler reddedilir.

Anketler modülü olan firmalarda Anket entegrasyonu sayfasında açılan kaynaklar da aynı anahtarlardır ve bu sayfada listelenir; davet gecikmesi gibi anket ayarları yine o sayfada değiştirilir.

Her isteğe eklenecek başlıklar

Başlık	Değer
`X-KuleConnect-Key`	Açık kimlik (`kc_…`)
`X-KuleConnect-Timestamp`	İsteğin gönderildiği an, Unix zaman damgası (saniye)
`X-KuleConnect-Signature`	`sha256=` ve ardından imza
`Content-Type`	`application/json` (gövdeli isteklerde)
`Accept`	`application/json`

Accept: application/json başlığını göndermeniz önerilir. /v1/ ile başlayan uçlar başlık olmasa da hataları JSON olarak döner; eksik ya da hatalı alanlar 422 ve errors nesnesiyle gelir.

İmzayı hesaplamak

Zaman damgasını, bir nokta ve isteğin ham gövdesini yan yana yazın: zaman_damgası + "." + gövde.
Bu metnin gizli anahtarla HMAC-SHA256 özetini alın ve onaltılık (hex) yazın.
Başına sha256= ekleyip X-KuleConnect-Signature başlığına koyun.

Örnek: zaman damgası 1767225600, gövde {"phone":"05321234567","code":"482913"} ise imzalanacak metin 1767225600.{"phone":"05321234567","code":"482913"} olur. Gövdeyi imzaladıktan sonra değiştirmeyin; tek bir boşluk farkı bile imzayı bozar. GET isteklerinde gövde boştur, imzalanacak metin yalnız 1767225600. olur.

Zaman damgası sunucu saatinden 5 dakikadan fazla saparsa istek reddedilir. Sunucunuzun saatini otomatik eşitlemeye ayarlayın.

Bağlantıyı sınamak

POST https://panel.ornek.com/v1/integrations/ping adresine gövdesiz (ya da {} gövdeyle) imzalı bir istek gönderin. Her şey doğruysa yanıt success: true ile birlikte kaynak adını, firma adınızı ve sunucu saatini döndürür.

Hata yanıtları

Kod	Ne zaman?
`401` `missing_key`	“X-KuleConnect-Key başlığı eksik.”
`401` `unknown_key`	“API anahtarı tanınmadı ya da kapalı.” Anahtar yanlış ya da kaynak kapalı.
`401` `stale_timestamp`	“X-KuleConnect-Timestamp eksik ya da 5 dakikadan eski.”
`401` `bad_signature`	“İmza doğrulanamadı.” Gizli anahtar ya da imzalanan metin hatalı.
`404`	İstenen kayıt bulunamadı.
`422`	Eksik ya da hatalı alan, veya işlem yapılamadı. Gövdedeki `message` nedeni yazar.
`429`	Dakikalık istek sınırı aşıldı.

Kimlik hatalarında yanıt {"success": false, "error": "…", "message": "…"} biçimindedir; error alanı tablodaki kısa kodu taşır.

İpucu: Gizli anahtarı yalnız sunucu tarafında saklayın; web sayfasına ya da mobil uygulamanın içine koymayın. API anahtarının genel anlamı için: API anahtarı.

Sorununuz çözülmedi mi?

Destek ekibine yazın

Santral API ile arama başlatma ve çağrı sorgulama