Skip to content

En İyi Uygulamalar ve Limitler

This content is not available in your language yet.

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.