Kalkhan API, lisans doğrulama, aktivasyon ve bayi entegrasyonu işlemlerini kendi sistemleriniz üzerinden yürütmenizi sağlar. Bu doküman uç noktaların istek/yanıt yapısını, kimlik doğrulama yöntemini ve hata kodlarını açıklar. Genel Bakış Kalkhan API, kaynak odaklı bir REST arayüzüdür. Tüm istek ve yanıt gövdeleri JSON formatında ve UTF-8 karakter kodlamasıyla iletilir. Bağlantılar TLS 1.2 ve üzeri ile şifrelenmek zorundadır; şifresiz (HTTP) istekler kabul edilmez. Base URLhttps://api.kalkhan.com.tr/v1 ProtokolHTTPS / TLS 1.2+ (zorunlu) Veri formatıJSON · Content-Type: application/json; charset=utf-8 Karakter kodlamasıUTF-8 Tarih formatıISO 8601 (UTC), örn. 2027-07-23T00:00:00Z Hız sınırıDakikada 120 istek (anahtar başına) Tüm uç nokta adresleri base URL ile birleştirilerek kullanılır. Örneğin lisans doğrulama uç noktasının tam adresi https://api.kalkhan.com.tr/v1/licenses/verify şeklindedir. Kurulum & Başlangıç Entegrasyona sıfırdan başlıyorsanız aşağıdaki adımları sırasıyla uygulayın. Tüm süreç ortalama 15 dakika sürer ve sunucu tarafında herhangi bir Kalkhan yazılımı kurmanızı gerektirmez — yalnızca HTTPS istek gönderebilen bir ortam yeterlidir. Ön koşullar Onaylanmış bir Kalkhan bayi hesabı (başvuru: iletişim formu) TLS 1.2 veya üzeri destekleyen bir sunucu ortamı (PHP 7.4+, Node.js 16+, .NET 6+, Python 3.8+ vb.) API anahtarını sunucu tarafında saklayabileceğiniz bir yapılandırma yöntemi (ortam değişkeni önerilir) Adım adım kurulum Bayi panelinize giriş yapın. Hesabınız yönetici onayından geçtikten sonra panel erişiminiz açılır. API anahtarı üretin. Panelde “API Anahtarları” bölümünden önce klk_test_ ön ekli bir test anahtarı oluşturun. Ortam değişkenlerini tanımlayın. Anahtarı ve base URL’i uygulamanızın yapılandırmasına ekleyin (aşağıdaki örnek). İlk isteği gönderin. Bağlantıyı doğrulamak için sağlık uç noktasını çağırın. Webhook adresinizi kaydedin. Lisans olaylarını anlık almak için panelden HTTPS webhook adresinizi tanımlayın. Canlıya geçin. Testler tamamlanınca klk_live_ anahtarına geçin; kod tarafında yalnızca anahtar değişir. 1) Ortam yapılandırması # .env KALKHAN_API_URL=https://api.kalkhan.com.tr/v1 KALKHAN_API_KEY=klk_test_xxxxxxxxxxxxxxxx KALKHAN_WEBHOOK_SECRET=whsec_xxxxxxxxxxxx 2) Bağlantı testi curl -s https://api.kalkhan.com.tr/v1/ping \ -H "Authorization: Bearer $KALKHAN_API_KEY" # Başarılı yanıt { "ok": true, "env": "test", "dealer": "BYI-1001" } İpucu: Test ortamında oluşturulan lisanslar gerçek faturalandırmaya girmez ve istediğiniz zaman silinebilir. Entegrasyonu canlıya almadan önce lisans oluşturma, doğrulama ve iptal akışlarının tamamını test anahtarıyla deneyin. Kimlik Doğrulama API istekleri Bearer şemasıyla, API anahtarınız kullanılarak yetkilendirilir. Anahtarı her isteğin Authorization başlığında göndermeniz gerekir. Authorization: Bearer klk_live_xxx Content-Type: application/json; charset=utf-8 Accept: application/json API anahtarınızı bayi panelinizdeki “API Anahtarları” bölümünden oluşturabilir ve iptal edebilirsiniz. Test ortamı için klk_test_, canlı ortam için klk_live_ ön ekli anahtarlar kullanılır. Güvenlik notu: API anahtarı gizli bir kimlik bilgisidir; yalnızca sunucu tarafında saklayın. Tarayıcı, mobil uygulama paketi veya herkese açık kod deposu içine gömmeyin. Anahtarın sızdığından şüphelenirseniz panelden hemen iptal edip yenisini oluşturun. Lisans Doğrulama Bir lisans anahtarının geçerliliğini, ürününü ve kalan süresini sorgulamak için kullanılır. Lisans anahtarları KLKN-XXXX-XXXX-XXXX-XXXX biçimindedir. MetotUç noktaYetki POST/licenses/verifyBearer API anahtarı İstek POST /v1/licenses/verify HTTP/1.1 Host: api.kalkhan.com.tr Authorization: Bearer klk_live_xxx Content-Type: application/json; charset=utf-8 { "key": "KLKN-4F2A-9C71-B3D8-A15E", "deviceId": "WIN-8f2c41ab9d", "productId": "kalkhan-av-windows" } Yanıt (200 OK) { "key": "KLKN-4F2A-9C71-B3D8-A15E", "status": "active", "product": "Kalkhan Anti-Virüs (Windows)", "edition": "business", "seats": 25, "seatsUsed": 11, "expiresAt": "2027-03-14T23:59:59Z" } AlanTipAçıklama statusstringactive, expired, suspended veya cancelled productstringLisansın ait olduğu ürünün görünen adı editionstringhome, business veya enterprise seatsintegerLisansın kapsadığı toplam cihaz sayısı expiresAtstringISO 8601 biçiminde bitiş tarihi (UTC) Geçersiz veya sistemde bulunmayan bir anahtar için 404 not_found, biçimi hatalı bir anahtar için 400 invalid_request döner. Lisans Oluşturma (Bayi) Yetkili bayilerin son kullanıcı adına yeni lisans üretmesi için kullanılır. Bu uç nokta yalnızca bayi yetkisine sahip API anahtarlarıyla çağrılabilir. MetotUç noktaYetki POST/licensesBayi API anahtarı İstek POST /v1/licenses HTTP/1.1 Host: api.kalkhan.com.tr Authorization: Bearer klk_live_xxx Content-Type: application/json; charset=utf-8 { "productId": "kalkhan-av-windows", "edition": "business", "seats": 25, "customer": { "name": "Örnek Bilişim A.Ş.", "email": "muhasebe@ornekbilisim.com.tr", "taxId": "1234567890", "taxOffice": "Ümraniye", "address": "Mithatpaşa Cd. No:116, Ümraniye/İstanbul" } } Yanıt (201 Created) { "key": "KLKN-7B10-CE45-2F93-D8A6", "status": "active", "product": "Kalkhan Anti-Virüs (Windows)", "edition": "business", "seats": 25, "amount": 34750.00, "currency": "TRY", "expiresAt": "2027-07-23T23:59:59Z" } Kurumsal satışlarda (edition değeri business veya enterprise olduğunda) fatura düzenlenebilmesi için customer.taxId (vergi kimlik numarası), customer.taxOffice (vergi dairesi) ve customer.address alanlarının gönderilmesi zorunludur. Bu alanlar eksik gönderildiğinde istek 400 invalid_request ile reddedilir. Bireysel (home) lisanslarda vergi alanları isteğe bağlıdır. Aynı müşteri ve ürün için kısa süre içinde tekrarlanan istekler 409 duplicate ile yanıtlanır; mükerrer lisans üretimini önlemek için isteğinize Idempotency-Key başlığı eklemeniz önerilir. Bayi API Bayilerin kendi lisans portföyünü ve satış özetini sorgulaması için iki uç nokta sunulur. MetotUç noktaAçıklama GET/dealer/licensesBayiye ait lisansların sayfalanmış listesi GET/dealer/statsSatış adedi, ciro ve yaklaşan yenileme özeti Sayfalama parametreleri ParametreVarsayılanAçıklama page1Görüntülenecek sayfa numarası (1’den başlar) limit25Sayfa başına kayıt sayısı (en fazla 100) status—İsteğe bağlı filtre: active, expired, cancelled İstek ve yanıt GET /v1/dealer/licenses?page=2&limit=25&status=active HTTP/1.1 Host: api.kalkhan.com.tr Authorization: Bearer klk_live_xxx { "data": [ { "key": "KLKN-4F2A-9C71-B3D8-A15E", "status": "active", "product": "Kalkhan Anti-Virüs (Windows)", "edition": "business", "seats": 25, "customer": "Örnek Bilişim A.Ş.", "expiresAt": "2027-03-14T23:59:59Z" } ], "pagination": { "page": 2, "limit": 25, "total": 143, "totalPages": 6 } } GET /dealer/stats uç noktası ise dönemsel özet döndürür: toplam aktif lisans sayısı, aylık satış adedi, toplam ciro ve önümüzdeki 30 gün içinde süresi dolacak lisans sayısı. Webhooks Lisans yaşam döngüsündeki değişiklikleri sistemlerinize anlık olarak iletmek için webhook kullanabilirsiniz. Hedef adresinizi bayi panelinden tanımlarsınız; Kalkhan bu adrese POST isteğiyle JSON gövde gönderir. OlayNe zaman tetiklenir? license.createdYeni bir lisans oluşturulduğunda license.expiredLisansın geçerlilik süresi dolduğunda license.cancelledLisans iptal edildiğinde veya iade işlendiğinde Örnek olay gövdesi POST /webhooks/kalkhan HTTP/1.1 X-Kalkhan-Signature: t=1784937600,v1=9f8c1d2b7e4a63f05c8b1a9d4e7f2c30b6a5d8e1f4c7b0a3d6e9f2c5b8a1d4e7 Content-Type: application/json; charset=utf-8 { "id": "evt_01J9X2K7QF", "event": "license.created", "createdAt": "2026-07-23T09:41:02Z", "data": { "key": "KLKN-7B10-CE45-2F93-D8A6", "product": "Kalkhan Anti-Virüs (Windows)", "edition": "business", "seats": 25, "expiresAt": "2027-07-23T23:59:59Z" } } İmza doğrulama Her webhook isteği X-Kalkhan-Signature başlığı ile imzalanır. İmza, zaman damgası ve ham istek gövdesinin HMAC-SHA256 ile webhook gizli anahtarınız kullanılarak hesaplanmış özetidir. İsteği işlemeden önce imzayı mutlaka doğrulayın ve 5 dakikadan eski zaman damgalarını reddedin. // Node.js — imza doğrulama const crypto = require('crypto'); function dogrula(rawBody, header, secret) { const parts = Object.fromEntries( header.split(',').map(p => p.split('=')) ); const beklenen = crypto .createHmac('sha256', secret) .update(parts.t + '.' + rawBody) .digest('hex'); return crypto.timingSafeEqual( Buffer.from(beklenen), Buffer.from(parts.v1) ); } Sunucunuz 2xx yanıt döndürmezse olay, artan aralıklarla (1 dk, 5 dk, 30 dk, 2 sa, 12 sa) en fazla 5 kez yeniden gönderilir. Aynı olayın birden fazla kez ulaşabileceğini varsayarak id alanına göre tekrar denetimi yapın. Hata Kodları Hatalar standart HTTP durum kodlarıyla döner ve gövdede makine tarafından okunabilir bir code ile açıklayıcı bir message içerir. HTTPKodAçıklama 400invalid_requestEksik veya biçimi hatalı parametre gönderildi 401unauthorizedAPI anahtarı yok, geçersiz veya iptal edilmiş 403forbiddenAnahtarın bu uç nokta için yetkisi bulunmuyor 404not_foundİstenen lisans veya kaynak bulunamadı 409duplicateKayıt zaten mevcut; mükerrer istek engellendi 429rate_limitedHız sınırı aşıldı; Retry-After başlığını bekleyin 500server_errorSunucu tarafında beklenmeyen bir hata oluştu Örnek hata yanıtı HTTP/1.1 400 Bad Request Content-Type: application/json; charset=utf-8 { "error": { "code": "invalid_request", "message": "customer.taxId alanı kurumsal lisanslar için zorunludur.", "field": "customer.taxId", "requestId": "req_01J9X2K7QF" } } Destek talebi oluştururken yanıttaki requestId değerini paylaşmanız, sorunun hızlıca incelenmesini sağlar. SDK & Örnekler Resmî SDK’lar hazırlanma aşamasındadır. Bu süreçte API’yi doğrudan HTTP üzerinden çağırabilirsiniz. Aşağıda lisans doğrulama isteğinin cURL ve JavaScript karşılıkları yer alıyor. cURL curl -X POST https://api.kalkhan.com.tr/v1/licenses/verify \ -H "Authorization: Bearer klk_live_xxx" \ -H "Content-Type: application/json; charset=utf-8" \ -d '{ "key": "KLKN-4F2A-9C71-B3D8-A15E", "deviceId": "WIN-8f2c41ab9d", "productId": "kalkhan-av-windows" }' JavaScript (fetch) const API_KEY = process.env.KALKHAN_API_KEY; // sunucu tarafında saklayın async function lisansDogrula(key, deviceId) { const res = await fetch( 'https://api.kalkhan.com.tr/v1/licenses/verify', { method: 'POST', headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json; charset=utf-8' }, body: JSON.stringify({ key, deviceId, productId: 'kalkhan-av-windows' }) } ); if (!res.ok) { const { error } = await res.json(); throw new Error(`${error.code}: ${error.message}`); } return res.json(); // { status, product, edition, seats, expiresAt } } lisansDogrula('KLKN-4F2A-9C71-B3D8-A15E', 'WIN-8f2c41ab9d') .then(lisans => console.log(lisans.status, lisans.expiresAt)) .catch(err => console.error('Doğrulama başarısız:', err.message)); Bu örnekler yalnızca sunucu tarafı kullanım içindir. API anahtarını tarayıcıda çalışan koda yerleştirmeyin; istemci uygulamalarınızdan gelen doğrulama isteklerini kendi arka uç servisiniz üzerinden geçirin. Kapalı beta API şu anda kapalı beta aşamasındadır; erişim için bilgi@kalkhan.com.tr adresinden başvurun. Beta süresince uç noktalarda geriye dönük uyumsuz değişiklikler yapılabilir.