1. Giriş ve Kapsam

1.1. Amaç

İşbu API Kullanım Politikası ("Politika"), Evaste API'lerinin kullanımına ilişkin koşulları, sınırlamaları ve gereksinimleri düzenlemektedir. API kullanarak Evaste'nin veri koruma ve rıza yönetimi hizmetlerine programatik erişim sağlayabilirsiniz.

1.2. Tanımlar

"API": Application Programming Interface - Evaste hizmetlerine programatik erişim sağlayan arayüz.

"API Anahtarı": API'ye erişim için kullanılan benzersiz kimlik doğrulama anahtarı.

"Endpoint": API üzerinden erişilebilen belirli bir işlev veya kaynak.

"Rate Limit": Belirli bir süre içinde yapılabilecek maksimum API çağrısı sayısı.

"Webhook": Evaste'nin belirli olaylar gerçekleştiğinde müşteri sistemlerine gönderdiği HTTP callback'leri.

"SDK": Software Development Kit - API entegrasyonunu kolaylaştıran yazılım kütüphaneleri.

1.3. Kapsam

Bu politika aşağıdaki API'leri kapsar:

• REST API (v2)
• GraphQL API
• Webhook Dağıtım Sistemi
• JavaScript SDK
• Server-side SDK'lar (Node.js, Python, PHP, Ruby)

2. API Erişimi ve Kimlik Doğrulama

2.1. API Erişim Gereksinimleri

API erişimi için:

• Aktif bir Evaste hesabı gereklidir
• API erişimi içeren bir abonelik planı gereklidir
• API Anahtarı oluşturulmalıdır
• İşbu Politika kabul edilmelidir

2.2. API Anahtarı Türleri

2.3. Kimlik Doğrulama Yöntemleri

• API Key Authentication: Header: X-API-Key: your_api_key_here
• Bearer Token Authentication: Header: Authorization: Bearer your_token_here
• OAuth 2.0 (Kurumsal planlar için): Authorization Code Flow, Client Credentials Flow

2.4. API Anahtarı Güvenliği

ZORUNLU güvenlik gereksinimleri:

• Secret Key'ler asla istemci tarafı kodda kullanılmamalıdır
• API anahtarları kaynak kodda saklanmamalıdır
• Ortam değişkenleri veya güvenli vault sistemleri kullanılmalıdır
• API anahtarları düzenli olarak döndürülmelidir (önerilen: 90 gün)
• Şüpheli aktivite tespit edildiğinde anahtar derhal iptal edilmelidir

2.5. IP Kısıtlaması (Opsiyonel)

Kurumsal müşteriler için:

• API erişimi belirli IP adreslerine kısıtlanabilir
• IP whitelist Dashboard'dan yapılandırılabilir
• CIDR notasyonu desteklenir
• Maksimum 50 IP adresi/aralığı tanımlanabilir

3. Kullanım Limitleri ve Kotalar

3.1. Rate Limiting

API çağrıları aşağıdaki limitlerle sınırlıdır:

3.2. Endpoint Bazlı Limitler

Belirli endpoint'ler için ek limitler uygulanır:

3.3. Burst Limit

Anlık trafik artışları için burst limit uygulanır:

• Pro: 200 istek/saniye (10 saniye burst)
• Kurumsal: 500 istek/saniye (30 saniye burst)
• Kurumsal Plus: 2,000 istek/saniye (60 saniye burst)

3.4. Rate Limit Headers

Her API yanıtında aşağıdaki header'lar döner: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-RateLimit-Retry-After

3.5. Rate Limit Aşımı

Limit aşıldığında:

• HTTP 429 (Too Many Requests) yanıtı döner
• Retry-After header'ı bekleme süresini belirtir
• Sürekli aşım hesap askıya alınmasına yol açabilir

3.6. Kota Yönetimi

• Gerçek zamanlı kullanım Dashboard'dan izlenebilir
• %80, %90 ve %100 eşiklerinde e-posta bildirimi gönderilir
• Ek kota API üzerinden veya Dashboard'dan satın alınabilir
• Kullanılmayan kotalar sonraki aya devretmez

4. API Kullanım Kuralları

4.1. Genel Kurallar

• API yalnızca belgelenen amaçlar için kullanılmalıdır
• Tüm API çağrıları HTTPS üzerinden yapılmalıdır
• API yanıtları önbelleğe alınabilir (Cache-Control direktiflerine uygun)
• Hata yanıtları uygun şekilde işlenmelidir

4.2. İstemci Gereksinimleri

Tüm API isteklerinde:

• Geçerli User-Agent header'ı sağlanmalıdır (Örnek: User-Agent: MyApp/1.0 (contact@example.com))
• Content-Type header'ı belirtilmelidir (Örnek: Content-Type: application/json)
• Accept header'ı belirtilmelidir (Örnek: Accept: application/json)

4.3. Veri Formatı

• İstekler: JSON formatında gönderilmelidir
• Yanıtlar: JSON formatında döner
• Tarihler: ISO 8601 formatında (UTC)
• Encoding: UTF-8

4.4. Pagination

Liste endpoint'leri için:

• Varsayılan sayfa boyutu: 20
• Maksimum sayfa boyutu: 100
• Cursor-based pagination tercih edilir
• Offset pagination desteği mevcuttur

4.5. Filtering ve Sorting

• Filtreler query parameter olarak gönderilir
• Çoklu filtreler AND mantığıyla birleştirilir
• Sorting: ?sort=field:asc veya ?sort=field:desc
• Çoklu sorting: ?sort=field1:asc,field2:desc

4.6. İdempotency

Kritik yazma işlemleri için:

• Idempotency-Key header'ı kullanılmalıdır
• Aynı key ile tekrarlanan istekler aynı sonucu döner
• Key'ler 24 saat geçerlidir
• UUID v4 formatı önerilir

5. Veri Güvenliği ve Gizlilik

5.1. Veri Şifreleme

• Tüm API trafiği TLS 1.2+ ile şifrelenir
• TLS 1.0 ve 1.1 desteklenmez
• Minimum cipher strength: AES-256
• Certificate pinning SDK'larda mevcuttur

5.2. Kişisel Veri İşleme

API üzerinden kişisel veri işlerken:

• GDPR ve KVKK gereksinimlerine uyulmalıdır
• Veri minimizasyonu ilkesi uygulanmalıdır
• Gereksiz veri toplanmamalı veya saklanmamalıdır
• Veri sahibi hakları desteklenmelidir

5.3. Veri Saklama

API üzerinden gönderilen veriler:

• Evaste sunucularında şifreli olarak saklanır
• Saklama süreleri Gizlilik Politikası'na tabidir
• Silme talepleri API üzerinden yapılabilir
• Veri dışa aktarma API üzerinden desteklenir

5.4. Audit Logging

Tüm API çağrıları loglanır:

• Çağrı zamanı, Endpoint, IP adresi, Kullanılan API anahtarı, Yanıt kodu, İşlem detayları
• Loglar 90 gün çevrimiçi erişilebilir
• 1 yıl arşivde saklanır
• Kurumsal müşteriler için genişletilmiş saklama mevcuttur

5.5. PII Maskeleme

API yanıtlarında:

• Tam e-posta adresleri maskelenir (u***@example.com)
• IP adresleri anonimleştirilebilir
• Hassas alanlar şifrelenebilir
• PII erişimi ayrıca yetkilendirilir

6. API Sürüm Yönetimi

6.1. Sürüm Politikası

• API sürümleri semantik versiyonlama kullanır (vMajor.Minor)
• Mevcut kararlı sürüm: v2
• Legacy sürüm: v1 (deprecated, 2026 Q4'te sonlandırılacak)

6.2. Sürüm Belirtme

API sürümü aşağıdaki yöntemlerle belirtilir:

• URL path (önerilen): /api/v2/consents
• Header: X-API-Version: 2
• Query parameter: ?api_version=2

6.3. Geriye Dönük Uyumluluk

Minor sürüm güncellemeleri geriye dönük uyumludur:

• Mevcut alanlar değiştirilmez veya kaldırılmaz
• Yeni opsiyonel alanlar eklenebilir
• Yeni endpoint'ler eklenebilir
• Davranış değişiklikleri breaking change olarak kabul edilir

6.4. Deprecation Politikası

• Deprecated özellikler en az 12 ay desteklenir
• Deprecation bildirimi: E-posta duyurusu, API yanıtında Deprecation header'ı, Dokümantasyon güncellemesi
• Sunset header'ı sonlandırma tarihini belirtir

6.5. Breaking Changes

Major sürüm değişiklikleri için:

• En az 6 ay öncesinden duyuru
• Geçiş rehberi sağlanır
• Paralel çalıştırma süresi (en az 6 ay)
• Geçiş desteği sunulur

7. Entegrasyon Gereksinimleri

7.1. SDK'lar

Resmi SDK'lar:

7.2. SDK Kullanımı

SDK kullanımı STRONGLY RECOMMENDED çünkü:

• Otomatik retry mekanizması
• Rate limit yönetimi
• Hata işleme
• Type safety
• Otomatik sürüm uyumu

7.3. Doğrudan API Entegrasyonu

SDK kullanılmadan doğrudan entegrasyon için:

• HTTP/1.1 veya HTTP/2 desteği
• JSON parse/serialize yeteneği
• TLS 1.2+ desteği
• Redirect takibi
• Timeout yönetimi (önerilen: 30 saniye)
• Retry mantığı (exponential backoff)

7.4. Webhook Entegrasyonu

Webhook'ları almak için:

• HTTPS endpoint sağlanmalıdır
• POST isteklerini kabul etmelidir
• 5 saniye içinde yanıt vermelidir
• 2xx yanıt kodu dönmelidir

Webhook İmza Doğrulama: Evaste-Signature: t=timestamp,v1=signature - İmza doğrulama ZORUNLUDUR.

7.5. Test Ortamı

Sandbox ortamı:

• Base URL: https://api.sandbox.evaste.co
• Test API anahtarları kullanılır
• Gerçek veri işlenmez
• Rate limitler production ile aynıdır
• Tüm özellikler test edilebilir

8. Hata Yönetimi ve Loglama

8.1. HTTP Durum Kodları

8.2. Hata Yanıt Formatı

Hata yanıtları JSON formatında döner ve şu bilgileri içerir: error.code, error.message, error.details, error.request_id, error.documentation_url

8.3. Hata Kodları

8.4. Retry Stratejisi

Geçiçi hatalar için (5xx, 429):

• Exponential backoff kullanın
• İlk retry: 1 saniye
• Maksimum retry: 5 deneme
• Maksimum bekleme: 32 saniye
• Jitter ekleyin

8.5. Request ID

Her API yanıtında benzersiz request ID döner: X-Request-ID: req_abc123xyz. Destek taleplerinde bu ID'yi paylaşın.

9. Yasaklanan Kullanımlar

9.1. Kesinlikle Yasak Olan Kullanımlar

Aşağıdaki faaliyetler API Erişiminin derhal sonlandırılmasına yol açar:

(a) Güvenlik İhlalleri

• API güvenlik açıklarını istismar etme
• Kimlik doğrulama atlatma girişimleri
• Yetkisiz veri erişimi
• SQL injection, XSS vb. saldırılar

(b) Kötüye Kullanım

• DDoS veya DoS saldırıları
• Spam veya toplu istenmeyen veri gönderimi
• Rate limit'leri kasıtlı olarak aşma
• Scraping veya veri kazıma

(c) Yasal İhlaller

• Yasadışı faaliyetler için API kullanımı
• Üçüncü taraf haklarını ihlal eden kullanım
• Veri koruma yasalarını ihlal eden kullanım

(d) Rekabet Amaçlı Kullanım

• Rakip ürün geliştirmek için API analizi
• Tersine mühendislik
• API'yi yeniden satma veya dağıtma

9.2. Kısıtlı Kullanımlar

Aşağıdakiler için önceden yazılı izin gerekir:

• Yüksek hacimli veri aktarımı (günlük 1M+ istek)
• Üçüncü taraf uygulamalarında API kullanımı
• White-label veya OEM entegrasyonları
• Akademik araştırma amaçlı kullanım

9.3. İhlal Sonuçları

10. Sorumluluk ve Garantiler

10.1. Evaste'nin Sorumlulukları

Evaste aşağıdakileri taahhüt eder:

• API'nin belgelenen şekilde çalışmasını sağlamak
• Güvenlik açıklarını zamanında düzeltmek
• Planlı bakımları önceden bildirmek
• Teknik destek sağlamak

10.2. Garanti Reddi

API "OLDUĞU GİBİ" sunulmaktadır. Evaste aşağıdakileri GARANTİ ETMEZ:

• Kesintisiz erişim
• Hatasız çalışma
• Belirli bir amaca uygunluk
• Üçüncü taraf sistemlerle uyumluluk

10.3. Sorumluluk Sınırlaması

Evaste, API kullanımından kaynaklanan dolaylı, arızi veya sonuç zararlarından, kar veya veri kaybından, iş kesintisinden, üçüncü taraf taleplerinden HİÇBİR KOŞULDA sorumlu tutulamaz. Maksimum sorumluluk: Son 12 ayda ödenen toplam ücret.

10.4. Kullanıcı Sorumlulukları

API kullanıcısı aşağıdakilerden sorumludur:

• API anahtarlarının güvenliği
• Entegrasyon hatalarından kaynaklanan sorunlar
• Rate limit'lere uyum
• Veri koruma yasalarına uyum
• Son kullanıcı verilerinin korunması

10.5. Tazminat

Kullanıcı, aşağıdakilerden kaynaklanan her türlü talep, zarar ve masrafa karşı Evaste'yi tazmin etmeyi kabul eder: API'nin kötüye kullanımı, Kullanım koşullarının ihlali, Üçüncü taraf haklarının ihlali, Yasadışı faaliyetler.

11. API Değişiklikleri ve Sonlandırma

11.1. Değişiklik Bildirimi

API değişiklikleri için:

11.2. Bildirim Kanalları

• api-updates@evaste.co e-posta listesi
• Developer blog
• API yanıtlarında header'lar
• Dashboard bildirimleri
• Status sayfası

11.3. API Erişimi Sonlandırma

Evaste, aşağıdaki durumlarda API erişimini sonlandırabilir:

• Kullanım koşullarının ihlali
• Hesap iptali
• Ödeme başarısızlığı
• Güvenlik tehditleri

11.4. Veri Dışa Aktarma

Sonlandırma öncesinde:

• 30 gün veri dışa aktarma süresi tanınır
• Tüm veriler API üzerinden dışa aktarılabilir
• Toplu export endpoint'i kullanılabilir
• Webhook geçmişi indirilebilir

12. Teknik Destek

12.1. Destek Kanalları

12.2. Destek Kapsamı

Dahil:

• API kullanım soruları
• Entegrasyon desteği
• Bug raporları
• Özellik talepleri

Hariç:

• Özel kod yazımı
• Üçüncü taraf entegrasyonları
• Performans optimizasyonu (Kurumsal plan hariç)

12.3. SLA (Kurumsal Planlar)

API destek SLA'sı için SLA Eki'ne bakınız.

12.4. Changelog ve Güncellemeler

• Changelog: https://docs.evaste.co/changelog
• RSS Feed: https://docs.evaste.co/changelog/rss
• GitHub Releases: github.com/evaste/api/releases

İletişim Bilgileri

Evaste API Ekibi

API Desteği: api-support@evaste.co

Güvenlik: security@evaste.co

Partnerlik: partners@evaste.co

Dokümantasyon: https://docs.evaste.co

API Referans: https://api.evaste.co/docs

Sandbox: https://api.sandbox.evaste.co