İçeriğe geç

En İyi Uygulamalar ve Limitler

Bulgaristan Vatandaşlık Sorgulama API’sini uygulamanıza entegre ederken en yüksek performansı elde etmek ve kesintisiz çalışmayı sağlamak için aşağıdaki mimari prensipleri uygulamanız önerilir.


⏱️ 1. Sorgulama Sıklığı ve Önbellekleme (Caching)

Section titled “⏱️ 1. Sorgulama Sıklığı ve Önbellekleme (Caching)”

Bulgaristan Adalet Bakanlığı (publicbg.mjs.bg), vatandaşlık dosyalarının durumlarını gün içinde sürekli değil, genellikle günde 1 veya 2 defa (resmi mesai saatlerinde) toplu olarak günceller.

  • Önerilen Sorgulama Aralığı: Aynı dosya için dakikada bir sorgu göndermek yerine, sonuçları kendi veritabanınızda veya bellek önbelleğinde (Redis, Memcached) en az 6 - 12 saat önbelleğe alınız.
  • Gereksiz Yükü Önleme: Önbellekteki verinin süresi dolmadan gelen kullanıcı taleplerine önbellekteki son durum bilgisini iletmeniz, uygulamanızın yanıt hızını 10ms altına düşürür.

🔄 2. Hata Yönetimi ve Yeniden Deneme (Retry Logic)

Section titled “🔄 2. Hata Yönetimi ve Yeniden Deneme (Retry Logic)”

Resmi portallarda dönem dönem yoğunluk veya güvenlik doğrulamaları yaşanabilir. API’miz bu durumlarda 503 Service Unavailable veya 504 Gateway Timeout döndürür.

  • Doğrudan peş peşe yeniden istek atmak yerine Üstel Gecikme (Exponential Backoff) kullanın.
  • İlk hata aldığınızda 3-5 saniye, tekrarında 10-15 saniye bekleyin.
  • Arka arkaya 3 denemeden sonra hala yanıt alınamıyorsa, kullanıcıya geçici portal yoğunluğu olduğunu belirten bilgilendirme mesajı gösterin ve dosyasını @Bulgaristanbot üzerinden otomatik takibe almasını önerin.

  1. Yalnızca Gerekli Veriyi İsteyin: Sistem sadece dosya numarası (reqNum) ve 6 haneli pin kodu ile çalışır. Kullanıcılarınızdan asla Bulgaristan kimlik numarası (EGN), pasaport kopyası veya kişisel biyometrik belgeler talep etmeyiniz.
  2. Korumalı İletişim: API çağrılarınızı her zaman https:// protokolü üzerinden gerçekleştirin.

📱 4. Telegram Bildirim Butonu ile Kullanıcı Deneyimini Artırın

Section titled “📱 4. Telegram Bildirim Butonu ile Kullanıcı Deneyimini Artırın”

Kullanıcılarınıza sadece web sayfanızda anlık durum göstermekle kalmayın; tek bir butonla durumlarını @Bulgaristanbot’a bağlamalarını sağlayın. Böylece:

  • Ukaz (Kararname) çıktığında anında bildirim alırlar.
  • Eksik evrak uyarısı durumunda süre aşımı yaşamazlar.
  • Sitenizi her gün tekrar tekrar ziyaret edip sorgu yapmak zorunda kalmazlar.

Örnek buton ve derin bağlantı detayları için Telegram Bot Entegrasyonu kılavuzunu inceleyebilirsiniz.