Sigortacılıkta API entegrasyonu: mimari ve en iyi uygulamalar

Sigorta API entegrasyonu, bir sigorta şirketinin teklif, poliçe, hasar, tahsilat ve doküman yeteneklerini; acenteler, brokerler, bankalar, dijital platformlar, servis sağlayıcılar ve kamu ya da sektör kurumlarıyla standart uygulama programlama arayüzleri (Application Programming Interface, API) üzerinden paylaşması demektir. Doğru kurulmuş bir API katmanı, yeni bir kanalın veya iş ortağının haftalar yerine çok daha kısa sürede devreye alınmasını sağlar; kötü kurulmuş olanı ise her yeni bağlantıyı ayrı bir projeye dönüştürür.

Sigortacılıkta entegrasyonun kendine özgü zorlukları vardır: eski core sistemlerin çoğu API düşünülerek tasarlanmamıştır, sektör kurumlarıyla bağlantılar hâlâ SOAP gibi eski protokollere dayanabilir, işlemler finansal ve hukuki sonuç doğurur ve veri, Kişisel Verilerin Korunması Kanunu (KVKK) kapsamında yoğun kişisel veri içerir. Bu yazıda sigorta şirketleri için API mimarisini, güvenlik, sürümleme ve hata yönetimi ilkelerini ve uygulanabilir bir proje yaklaşımını ele alıyoruz.

Sigorta şirketleri hangi sistemlerle API üzerinden entegre olur?

Sigorta şirketleri; satış kanalları, finansal kurumlar, sektör ve kamu veri kaynakları ve operasyonel hizmet sağlayıcılarla entegre olur. Her grubun işlem tipi, hacmi ve güvenlik gereksinimi farklıdır.

Sektör kurumlarıyla bağlantının ayrıntıları için SBM ve TRAMER entegrasyonu, acentelerle kurulan ilişkinin kullanıcı tarafı için ise acente portalı yazılarımıza bakabilirsiniz.

Sigorta API mimarisi nasıl katmanlandırılır?

Sağlıklı bir sigorta API mimarisi; core sistemleri saran sistem API'leri, iş süreçlerini birleştiren süreç API'leri ve kanallara özel deneyim API'leri olarak üç katmanda kurgulanır ve dış dünyaya tek bir API gateway üzerinden açılır. Bu ayrım, core sistemdeki bir değişikliğin tüm iş ortaklarını etkilemesini engeller.

• Sistem API'leri: Poliçe yönetim sistemi, hasar sistemi, tahsilat ve müşteri sistemlerinin yeteneklerini sade ve kararlı arayüzlerle sunar. Eski sistemin veri modeli burada kanonik bir modele çevrilir.
• Süreç API'leri: "Teklif al", "poliçeleştir", "hasar ihbarı aç" gibi iş süreçlerini birden fazla sistem API'sini birleştirerek yürütür.
• Deneyim API'leri: Mobil uygulama, acente portalı veya belirli bir iş ortağı için ihtiyaca göre şekillendirilmiş arayüzler sunar.
• API gateway: Kimlik doğrulama, yetkilendirme, istek sınırlama, trafik yönlendirme ve kayıt işlevlerini merkezi olarak üstlenir.

Kanonik veri modeli bu mimarinin kalbidir. Ürün, teminat, risk nesnesi, sigortalı ve poliçe gibi kavramların tek bir sözlükle tanımlanması, her yeni entegrasyonda yeniden eşleme yapma ihtiyacını azaltır. Servislerin nasıl bölüneceği sorusu için sigortacılıkta mikroservis mimarisi yazımız tamamlayıcı bir çerçeve sunar.

Senkron mu, asenkron mu?

Kullanıcının anında cevap beklediği işlemler senkron, sonucu sonradan bildirilebilecek veya birden fazla sisteme yayılan işlemler asenkron tasarlanmalıdır. Teklif ve fiyat sorgusu tipik olarak senkrondur; poliçe basımı, sektör kurumlarına bildirim, muhasebe kaydı ve reasürans aktarımı ise asenkron yürütülmeye daha uygundur.

Asenkron akışlarda iş ortağına sonucu bildirmek için webhook, iç sistemler arasında ise bir mesaj kuyruğu veya olay akışı platformu kullanılır. Veritabanına yazılan işlem ile yayımlanan olayın tutarlı kalması için giden kutusu (outbox) deseni gibi yöntemler, "poliçe oluştu ama bildirimi gitmedi" türündeki tutarsızlıkları önler.

Sigorta API'lerinde güvenlik nasıl sağlanır?

Sigorta API güvenliği; iş ortağının kimliğinin güçlü biçimde doğrulanması, her çağrının yalnızca yetkili olduğu veriye erişmesi, trafiğin şifrelenmesi ve kötüye kullanımın sınırlandırılması ile sağlanır. Bu önlemler, API'lerin taşıdığı kişisel ve finansal veri nedeniyle zorunlu kabul edilmelidir.

• Sistemler arası erişimde OAuth 2.0 istemci kimlik bilgileri akışı ve kısa ömürlü erişim belirteçleri (token) kullanın.
• Yüksek hassasiyetli bağlantılarda karşılıklı TLS (mTLS) ile istemci sertifikası doğrulaması ekleyin.
• Yetkilendirmeyi nesne düzeyinde yapın: bir acente yalnızca kendi poliçelerine erişebilmeli; kimlik doğrulaması yeterli sayılmamalıdır.
• İstek sınırlama (rate limiting) ve kota tanımlarıyla kötüye kullanımı ve hatalı istemci döngülerini engelleyin.
• Girdi doğrulamasını şema düzeyinde yapın; beklenmeyen alanları reddedin.
• Kayıtlarda T.C. kimlik numarası, kart bilgisi ve sağlık verisi gibi alanları maskeleyin.
• Yanıtlarda yalnızca işlem için gerekli veriyi döndürün; veri minimizasyonunu API tasarımının parçası yapın.

OWASP API Security Top 10 listesi, API'lere özgü zafiyetleri gözden geçirmek için iyi bir kontrol çerçevesidir. Daha geniş güvenlik mimarisi için sigortacılıkta siber güvenlik yazımızı inceleyebilirsiniz.

Sürümleme, hata yönetimi ve idempotency neden kritik?

Sürümleme iş ortaklarının entegrasyonunu bozmadan API'yi geliştirmeyi, hata yönetimi sorunların hızla anlaşılmasını, idempotency ise aynı isteğin tekrarlanmasıyla mükerrer poliçe veya mükerrer tahsilat oluşmasını engeller. Sigortacılıkta işlemler finansal sonuç doğurduğu için bu üç konu, teknik ayrıntı değil iş sürekliliği meselesidir.

Sürümleme: Geriye dönük uyumu bozan her değişiklik yeni bir ana sürümle yayımlanmalı, eski sürüm için kullanımdan kaldırma takvimi iş ortaklarına önceden duyurulmalıdır. Alan eklemek gibi uyumlu değişiklikler mevcut sürümde yapılabilir; bunun için istemcilerin bilinmeyen alanları yok sayacak biçimde tasarlanması teşvik edilmelidir.

Hata yönetimi: Tüm API'lerde tutarlı bir hata modeli kullanılmalıdır: makinece okunabilir hata kodu, insan için açıklama, hatalı alan bilgisi ve izleme için bir bağıntı kimliği (correlation ID). "Kabul kuralına takıldı" gibi iş hataları ile "servis geçici olarak erişilemiyor" gibi teknik hatalar ayrı kodlarla ifade edilmelidir; çünkü istemcinin birinde tekrar denemesi, diğerinde denememesi gerekir.

Idempotency: Poliçeleştirme, tahsilat ve iade gibi işlemlerde istemci her isteğe benzersiz bir anahtar eklemeli, sunucu aynı anahtarla gelen tekrar istekte yeni işlem yapmak yerine ilk sonucu döndürmelidir. Ağ zaman aşımında istemcinin işlemin gerçekleşip gerçekleşmediğini bilmediği durumlar, sigortacılıkta mükerrer poliçelerin en yaygın nedenidir.

Bunlara ek olarak her dış bağımlılık için zaman aşımı, sınırlı ve artan aralıklı tekrar deneme ve devre kesici (circuit breaker) tanımlanmalı; tüm çağrılar bağıntı kimliğiyle uçtan uca izlenebilir olmalıdır.

API entegrasyon projesi adım adım nasıl yürütülür?

API entegrasyon projesi; kapsamın ve sözleşmenin netleştirilmesiyle başlar, test ortamında karşılıklı doğrulamayla ilerler ve izleme altında kademeli canlıya geçişle tamamlanır.

1. İş ihtiyacını ve kapsamı belirleyin: hangi ürünler, hangi işlemler, hangi hacim ve hangi hizmet seviyesi.
2. API sözleşmesini OpenAPI gibi makinece okunabilir bir formatta önce yazın; iş ortağıyla sözleşme üzerinde anlaşın.
3. Kimlik doğrulama, yetkilendirme ve veri paylaşımının hukuki dayanağını netleştirin; gerekiyorsa veri işleme sözleşmesi yapın.
4. Test ortamını, örnek verileri ve sahte (mock) servisleri iş ortağının erişimine açın.
5. Sistem ve süreç API'lerini geliştirin; kanonik veri modeline eşlemeyi tamamlayın.
6. Fonksiyonel, sözleşme, yük ve güvenlik testlerini çalıştırın; hata senaryolarını özellikle test edin.
7. İzleme panolarını ve alarm eşiklerini tanımlayın; hata oranı, yanıt süresi ve iş hacmi izlensin.
8. Sınırlı hacimle canlıya geçin, ilk işlemleri birlikte doğrulayın ve hacmi kademeli artırın.

ProdayTech olarak entegrasyon projelerinde API sözleşmesini kod yazılmadan önce iş ortağıyla birlikte netleştirmeyi ve sahte servislerle paralel geliştirmeyi standart yaklaşım olarak uyguluyoruz.

Sigorta API entegrasyonu için kontrol listesi

• Her API için yazılı bir sözleşme (OpenAPI) ve değişiklik geçmişi var.
• Kanonik veri modeli ve alan sözlüğü tanımlı.
• OAuth 2.0, gerekli yerlerde mTLS ve nesne düzeyinde yetkilendirme uygulanıyor.
• Hassas alanlar kayıtlarda maskeleniyor.
• Poliçeleştirme, tahsilat ve iade işlemlerinde idempotency anahtarı zorunlu.
• İş ve teknik hatalar ayrı kodlarla dönüyor.
• Tüm dış çağrılarda zaman aşımı, tekrar deneme ve devre kesici tanımlı.
• Sürümleme ve kullanımdan kaldırma politikası iş ortaklarıyla paylaşıldı.
• Bağıntı kimliğiyle uçtan uca izleme ve alarm yapısı çalışıyor.
• İş ortakları için test ortamı ve güncel dokümantasyon erişilebilir.