İzin yönetimini elle yürütmek belli bir hacimden sonra sürdürülemez hâle gelir. İYS API entegrasyonu, izin ekleme, sorgulama ve ret takibini gönderim akışınızın doğal bir parçası hâline getirir. Bu rehber, entegrasyonu yapacak geliştirici ekipler için pratik bir yol haritasıdır.
Kavramsal arka plan için İYS nedir rehberimize, entegratör seçimi için bu yazımıza bakabilirsiniz.
Başlamadan Önce: Mimari Kararlar
Kod yazmadan önce üç şeye karar verin. Bu kararlar sonradan değiştirilmesi en pahalı olan kısımlardır.
1. İzin kaydı nerede tutulacak?
İYS tek doğruluk kaynağı olsa da, her sorguda İYS'ye gitmek pratik değildir. Kendi tarafınızda bir izin tablosu tutun; bu tablo İYS ile senkron kalsın. Tabloda en az şunlar bulunmalı: alıcı, kanal, durum, kaynak, son güncelleme zamanı ve son senkronizasyon zamanı.
2. Senkronizasyon yönü ne olacak?
İki yön de gereklidir: sizden İYS'ye yeni izinler, İYS'den size retler ve değişiklikler. Tek yönlü kurulan entegrasyonlar, ret körlüğü yaratır ve en sık karşılaşılan tasarım hatasıdır.
3. İşlemler senkron mu asenkron mu yürütülecek?
Tekil işlemler senkron yapılabilir. Ancak toplu işlemler asenkrondur: isteği gönderirsiniz, bir işlem kimliği (GUID) alırsınız, sonucu daha sonra bu kimlikle sorgularsınız. Bu nedenle kuyruk (queue) ve zamanlanmış görev (cron/worker) altyapınız baştan planlanmalıdır.
Adım 1: Kimlik Doğrulama
API erişimi token tabanlıdır. Tipik akış şöyledir:
- Size verilen kimlik bilgileriyle token uç noktasına istek atarsınız.
- Belirli bir süre geçerli bir erişim token'ı alırsınız.
- Sonraki tüm isteklerde bu token'ı yetkilendirme başlığında gönderirsiniz.
- Süre dolduğunda token yenilenir.
Yaygın hata: Her istek için yeni token almak. Token'ı önbellekte tutun, süresi dolmadan yenileyin ve eşzamanlı isteklerde tek bir yenileme çalışacak şekilde kilitleyin. Aksi hâlde gereksiz istek üretir ve hız sınırına takılırsınız.
Güvenlik: Kimlik bilgilerini koda gömmeyin; ortam değişkeni ya da gizli anahtar deposu kullanın. Token'ı istemci tarafına (tarayıcı, mobil uygulama) hiçbir koşulda göndermeyin.
Adım 2: İzin Ekleme
Yeni bir onay aldığınız anda (web formu, çağrı merkezi, mobil uygulama) izni İYS'ye yazarsınız. Gönderilen kayıtta şu alanlar bulunur:
- Alıcı: Telefon numarası veya e-posta adresi
- İzin türü: SMS, e-posta veya arama
- İzin kaynağı: Onayın alındığı yol
- Durum: Onay ya da ret
- Zaman: Onayın alındığı an
Kritik ayrıntı — numara normalizasyonu: Kullanıcıdan gelen numara "0532 123 45 67", "+90 532 1234567" veya "(532) 123-45-67" biçiminde olabilir. Kaydetmeden önce tek bir kanonik biçime dönüştürün. Normalize edilmemiş numaralar sessizce eşleşmez ve izin kaybına yol açar.
Kritik ayrıntı — idempotenslik: Aynı izin iki kez gönderilebilir (kullanıcı formu iki kez gönderdi, iş yeniden denendi). Kendi tarafınızda bir tekilleştirme anahtarı tutun ve tekrarlı yazmaları engelleyin.
Adım 3: Sorgulama
İki tür sorgu vardır:
- Tekil sorgu: Anlık kontrol gerektiren yerlerde (form doğrulama, çağrı merkezi ekranı) kullanılır. Senkron çalışır.
- Toplu sorgu: Kampanya listesi temizliğinde kullanılır. Tek istekte gönderilebilecek kayıt sayısı sınırlıdır; listeyi parçalara bölün.
Toplu sorgu akışı:
- Listeyi uygun büyüklükte parçalara ayırın.
- Her parça için istek gönderip dönen işlem kimliğini veritabanına yazın.
- Bir arka plan görevi, bu kimlikleri düzenli aralıklarla yoklayarak sonuçları toplasın.
- Sonuçları kendi izin tablonuza işleyin.
- Gönderim listesini yalnızca onay durumundaki kayıtlardan oluşturun.
Ayrıntı için İYS sorgulama rehberimize bakın.
Adım 4: Ret Senkronizasyonu
Entegrasyonun en çok ihmal edilen ama en riskli parçasıdır. Alıcı iznini İYS üzerinden geri çektiğinde bu bilgi sizin sisteminize otomatik düşmelidir. İki yaklaşım vardır:
- Bildirim tabanlı: Entegratörünüz webhook veya benzeri bir bildirim sunuyorsa, ret anında sisteminize yazılır. Tercih edilen yöntemdir.
- Yoklama tabanlı: Düzenli aralıklarla değişiklikleri sorgularsınız. Aralık ne kadar uzunsa risk o kadar büyür.
Hangi yöntemi kullanırsanız kullanın, gönderim öncesi son bir doğrulama adımını atlamayın. Ayrıntı: İYS ret yönetimi.
Adım 5: Hata Yönetimi
Hataları iki gruba ayırın ve farklı davranın:
| Hata tipi | Örnek | Davranış |
|---|---|---|
| Geçici | Zaman aşımı, hız sınırı, 5xx yanıtlar | Üstel geri çekilme ile yeniden dene; belirli sayıda denemeden sonra kuyruğa al. |
| Kalıcı | Geçersiz numara biçimi, yetkisiz marka, doğrulama hatası | Yeniden deneme; kaydı hata tablosuna yaz ve operasyona bildir. |
Sessiz başarısızlık en tehlikeli senaryodur. Toplu bir işlemde 10.000 kaydın 400'ü hata almışsa ve bunu kimse görmüyorsa, o 400 kişi ya izinsiz mesaj alır ya da izinli olduğu hâlde listeden düşer. Hata oranı için eşik belirleyin ve aşıldığında uyarı üretin.
Adım 6: Test ve Canlıya Geçiş
Canlıya geçmeden önce şu kontrol listesini tamamlayın:
- Test (sandbox) ortamında tüm uç noktalar denendi
- Token yenileme, süre dolumu senaryosunda test edildi
- Numara ve e-posta normalizasyonu, gerçek veri örnekleriyle doğrulandı
- Toplu işlemde parçalama ve sonuç toplama uçtan uca çalıştırıldı
- Geçici ve kalıcı hata senaryoları ayrı ayrı denendi
- Ret senkronizasyonu tetiklenip kendi tablonuza yansıdığı doğrulandı
- Hata oranı için izleme ve uyarı kuruldu
- Kimlik bilgileri ortam değişkenine taşındı, kodda gömülü değer kalmadı
- Denetim için istek/yanıt kayıtları saklanıyor (kişisel veri maskelenerek)
- Mevcut izinlerin ilk toplu yüklemesi yapıldı ve raporu kontrol edildi
Performans İçin Pratik Öneriler
- Toplu işlem tercih edin. 10.000 kayıt için 10.000 tekil istek yerine parçalı toplu istek kullanın.
- Sorgu sonucunu kısa süreli önbelleğe alın — ama gönderim öncesi son doğrulamayı önbellekten yapmayın.
- Kuyruk kullanın. Kullanıcı isteğini bloklamadan, izin yazma işini arka plana alın.
- Kampanya saatlerinde eşzamanlılığı sınırlayın. Hız sınırına takılmak, tüm kuyruğu yavaşlatır.
Sık Sorulan Sorular
İYS API entegrasyonu ne kadar sürer?
Entegratör API'si üzerinden çalışıldığında temel akış (kimlik doğrulama, izin ekleme, sorgulama) genellikle birkaç gün içinde kurulabilir. Süreyi uzatan kısım genellikle mevcut izin verinizin temizlenmesi ve ilk toplu yüklemedir.
Toplu işlemler neden asenkron?
Çok sayıda kaydın doğrulanması zaman alır. Sistem isteği kabul edip bir işlem kimliği döner, işi arka planda yürütür ve sonucu bu kimlikle sunar. Bu sayede istek zaman aşımına uğramaz.
Kendi sistemimde izin tablosu tutmalı mıyım?
Evet. Her sorguda İYS'ye gitmek pratik değildir. Kendi tablonuzu tutup İYS ile senkron kalmak hem hız hem de denetim izi açısından doğru yaklaşımdır.
Test ortamı olmadan entegrasyon yapabilir miyim?
Yapılmamalıdır. Canlı ortamda deneme, gerçek izin kayıtlarını bozma riski taşır. Test ortamı sunmayan bir sağlayıcı, bu başlıkta ciddi bir uyarı işaretidir.
Özetle: Token'ı önbelleğe alın, numaraları normalize edin, toplu işlemleri asenkron kurgulayın, retleri iki yönlü senkronize edin ve hataları sessizce yutmayın. Selfiys İYS API'sinin uç noktaları ve örnekleri için API dokümantasyonuna bakın.
