TEFAS API: Türkiye Fon Verilerine Kolay Erişim

Go, Redis ve modern web scraping teknikleri kullanarak Türkiye Elektronik Fon Alım Satım Platformu (TEFAS) için kapsamlı bir RESTful API nasıl geliştirdim ve kullanımı hakkında bilgi vereceğim.

---

🚀 Giriş

Türkiye Elektronik Fon Alım Satım Platformu (TEFAS), Türkiye'deki yatırım fonu işlemlerinin merkezi hub'ıdır ve yıllık milyarlarca dolarlık işlem hacmi gerçekleştirir. TEFAS fon verilerine erişim için bir web arayüzü sağlasa da, geliştiriciler ve finansal uygulamalar için bu zengin bilgi kaynağına programatik erişim sağlayacak resmi bir API bulunmuyordu.

İşte tefas-api burada devreye giriyor - bu açığı kapatmak için geliştirdiğim yüksek performanslı, üretime hazır bir API. Bu makale, gerçek zamanlı fon bilgileri, geçmiş veriler ve ticaret raporları sunan kapsamlı bir finansal veri API'si oluşturma yolculuğunu anlatıyor.

🎯 Proje Genel Bakış

tefas-api, Türk yatırım fonu verilerine programatik erişim sağlayan bir RESTful API servisidir. Go ile geliştirilmiş ve kurumsal seviye mimari desenler izleyen bu proje şunları sunuyor:

• 50+ Portföy Yönetim Şirketi Verisi
• Gerçek Zamanlı Fon Bilgileri
• Geçmiş Performans Verileri
• İşlem Hacmi Raporları
• Kurumsal Analizler
• Etkileşimli API Dokümantasyonu

🔗 Proje Bağlantıları

• Canlı Demo: API Dokümantasyonu
• Geliştirici: Serif Colakel

🏗️ Mimari & Teknoloji Yığını

Temel Teknolojiler

Backend Framework: Gin HTTP framework ile Go
Önbellekleme: Yüksek performanslı veri önbellekleme için Redis
Web Scraping: Güvenilir veri çıkarımı için ChromeDP
Dokümantasyon: Swagger UI ile OpenAPI 3.1
Konteynerizasyon: Multi-stage build'ler ile Docker
İş Zamanlama: Özel cron job yönetim sistemi

Mimari Desen

Proje, temiz mimari prensipleri ile Standard Go Project Layout izliyor:

/cmd/api/           - Uygulama giriş noktası
/internal/          - Özel uygulama kodu
  /config/          - Konfigürasyon yönetimi
  /handler/         - HTTP istek işleyicileri (Gin)
  /middleware/      - HTTP middleware (CORS, auth, rate limiting)
  /model/           - Veri modelleri ve DTO'lar
  /repository/      - Veri erişim katmanı (Redis önbellekleme)
  /service/         - İş mantığı katmanı
  /validator/       - Girdi doğrulama
/pkg/               - Paylaşılabilir kütüphane kodu
  /logger/          - Yapılandırılmış loglama
  /scraper/         - ChromeDP ile web scraping
  /cron/            - İş zamanlama sistemi
/api/               - OpenAPI/Swagger spesifikasyonları
/web/               - Statik varlıklar ve dokümantasyon

Bu yapı şunları sağlar:

• Endişelerin Ayrılması: Her katmanın tek sorumluluğu var
• Test Edilebilirlik: Bağımlılıklar enjekte edilir ve kolayca mock'lanabilir
• Sürdürülebilirlik: Kod mantıklı şekilde organize edilmiş ve Go konvansiyonlarını takip ediyor
• Ölçeklenebilirlik: Yeni özellikler mevcut kodu etkilemeden eklenebilir

🚀 Ana Özellikler

1. 💰 Kapsamlı Fon Verisi API'si

Fon Keşfi

GET /api/v1/funds

Temel bilgileri ile birlikte tüm mevcut fonları döndürür.

Bireysel Fon Detayları

GET /api/v1/funds/{code}

Performans metrikleri, portföy kompozisyonu ve geçmiş veri görselleştirmeleri dahil detaylı fon bilgileri.

Portföy Yönetim Şirketleri

GET /api/v1/funds/companies

Türkiye'de faaliyet gösteren tüm 50+ portföy yönetim şirketinin tam listesi:

{
  "data": [
    {
      "code": "AKP",
      "company": "AK PORTFÖY YÖNETİMİ A.Ş."
    },
    {
      "code": "ISP",
      "company": "İŞ PORTFÖY YÖNETİMİ A.Ş."
    }
  ],
  "meta": { "total": 50 },
  "success": true
}

2. 📊 Performans & Analitik API'leri

Fon Getiri Analizi

GET /api/v1/funds/returns?fundType=1&startDate=01.01.2024&endDate=31.12.2024

Şu desteklerle kapsamlı getiri analizi:

• Fon Tipi Filtreleme: Menkul Kıymet, Emeklilik, BYF, Gayrimenkul, Girişim Sermayesi
• Özel Tarih Aralıkları: Esnek tarih filtreleme
• Sayfalama Desteği: Büyük veri setlerini verimli şekilde işleme

Fon Büyüklük Analitiği

GET /api/v1/funds/sizes?fundType=1

Portföy büyüklük analizi ve büyüme metrikleri.

Geçmiş Veriler

GET /api/v1/funds/historical?fundType=1&startDate=01.08.2025&endDate=16.08.2025

Şu özelliklerle zaman serisi fon performans verisi:

• 30 dakika önbellek TTL'si optimal performans için
• Tarihler belirtilmezse varsayılan 7 günlük aralık
• Büyük veri setleri için sayfalama desteği

Fon Karşılaştırması

GET /api/v1/funds/comparison?fundType=YAT&islemDurum=1

Detaylı metriklerle fonlar arası yönetim ücreti karşılaştırması.

3. 📈 Kurumsal İşlem Raporları

İşlem Kurumları Analitiği

GET /api/v1/funds-reports/trading-institutions?year=2025&month=8

TEFAS fonlarında işlem yapan kurumlarla ilgili istatistikler.

İşlem Hacmi Raporları

• Toplam İşlem Hacmi: Pazar geneli işlem analizi
• Üye Bazlı Hacim: Kuruma özel işlem kalıpları
• Fon Bazlı Hacim: Bireysel fon işlem istatistikleri
• Üye Hisse Bakiyeleri: Fon tipine göre holding analizi

4. ⏰ Gelişmiş İş Yönetimi

Otomatik veri yenileme için yerleşik cron job sistemi:

POST /api/v1/cron/jobs
{
  "name": "daily-fund-refresh",
  "schedule": "0 2 * * *",
  "function": "fund-data-refresh",
  "enabled": true
}

Mevcut İş Tipleri:

• fund-data-refresh: Fon verisi önbelleğini günceller
• fund-list-refresh: Fon listelerini yeniler
• system-health-check: Sistem sağlığını izler

5. 🖼️ Görsel Yönetim Sistemi

Şirket logoları ve varlıkları yükleme ve yönetme:

POST /api/v1/images/
Content-Type: multipart/form-data

Özellikler:

• Çoklu Format Desteği: JPEG, PNG, GIF, WebP
• Güvenli UUID Tabanlı İsimlendirme: Dosya çakışmalarını önler
• Admin Kimlik Doğrulama: Güvenli erişim kontrolü
• Otomatik Servis: Görsellere doğrudan URL erişimi

🔧 Teknik Uygulama

ChromeDP ile Web Scraping

En zorlu noktalardan biri TEFAS web arayüzünden güvenilir şekilde veri çıkarmaktı. Sağlamlığı nedeniyle ChromeDP'yi tercih ettim:

func (s *Scraper) ScrapeFundData(ctx context.Context, fundCode string) (*model.Fund, error) {
    ctx, cancel := chromedp.NewContext(ctx)
    defer cancel()

    var result string

    err := chromedp.Run(ctx,
        chromedp.Navigate(fmt.Sprintf("https://www.tefas.gov.tr/FonAnaliz.aspx?fon=%s", fundCode)),
        chromedp.WaitVisible("#fund-data", chromedp.ByID),
        chromedp.OuterHTML("#fund-data", &result),
    )

    if err != nil {
        return nil, fmt.Errorf("scraping failed: %w", err)
    }

    return s.parseHTML(result)
}

ChromeDP'nin Faydaları:

• JavaScript Çalıştırma: Dinamik içerik yüklemeyi işler
• Güvenilir Bekleme: Elementlerin görünür olmasını bekler
• Performans: Hız için headless operasyon
• Yeniden Deneme Mantığı: Yerleşik hata işleme ve yeniden denemeler

Redis Önbellekleme Stratejisi

Scraping yükünü minimize etmek ve yanıt sürelerini iyileştirmek için akıllı önbellekleme sistemi:

func (r *Repository) GetFundWithCache(ctx context.Context, code string) (*model.Fund, error) {
    cacheKey := fmt.Sprintf("fund:%s", code)

    // Önce önbelleği dene
    cached, err := r.client.Get(ctx, cacheKey).Result()
    if err == nil {
        var fund model.Fund
        if json.Unmarshal([]byte(cached), &fund) == nil {
            return &fund, nil
        }
    }

    // Önbellek kaybı - taze veri scrapla
    fund, err := r.scraper.ScrapeFundData(ctx, code)
    if err != nil {
        return nil, err
    }

    // 30 dakika önbellekle
    data, _ := json.Marshal(fund)
    r.client.Set(ctx, cacheKey, data, 30*time.Minute)

    return fund, nil
}

Önbellek Stratejisi:

• Fon verisi için 30 dakika TTL
• Statik veri için 6 saat TTL
• Geçmiş raporlar için 24 saat TTL
• Şirket verisi için bellekte önbellekleme

Hız Sınırlama & Güvenlik

Hem API'yi hem de kaynak sistemleri korumak için kapsamlı güvenlik önlemleri:

func NewRateLimiter(requestsPerMinute, burstSize int) *RateLimiter {
    return &RateLimiter{
        clients:   make(map[string]*clientLimiter),
        rate:      rate.Limit(requestsPerMinute),
        burstSize: burstSize,
        mutex:     &sync.RWMutex{},
    }
}

func (rl *RateLimiter) RateLimit() gin.HandlerFunc {
    return func(c *gin.Context) {
        clientIP := c.ClientIP()

        if !rl.allowRequest(clientIP) {
            c.JSON(http.StatusTooManyRequests, gin.H{
                "error": "Rate limit exceeded",
                "retry_after": 60,
            })
            c.Abort()
            return
        }

        c.Next()
    }
}

Güvenlik Özellikleri:

• IP Tabanlı Hız Sınırlama: 20 burst kapasitesi ile dakikada 100 istek
• Admin Kimlik Doğrulama: Çoklu auth yöntemleri (Bearer, Header, Query)
• CORS Koruması: Yapılandırılabilir cross-origin politikaları
• İstek Loglama: Kapsamlı denetim kayıtları
• Girdi Doğrulama: Sıkı parametre doğrulama

Hata İşleme & Loglama

Yapılandırılmış loglama ve kapsamlı hata işleme:

type APIError struct {
    Error         string    `json:"error"`
    Details       string    `json:"details,omitempty"`
    Status        int       `json:"status,omitempty"`
    CorrelationID string    `json:"correlationId,omitempty"`
    Suggestion    string    `json:"suggestion,omitempty"`
    Severity      string    `json:"severity,omitempty"`
    OccurredAt    time.Time `json:"occurredAt,omitempty"`
}

func (h *Handler) errorResponse(c *gin.Context, status int, message string, details string) {
    correlationID := c.GetString("request_id")

    h.logger.ErrorWithFields("API Error", map[string]interface{}{
        "status":         status,
        "message":        message,
        "details":        details,
        "correlation_id": correlationID,
        "client_ip":      c.ClientIP(),
        "user_agent":     c.GetHeader("User-Agent"),
    })

    c.JSON(status, APIError{
        Error:         message,
        Details:       details,
        Status:        status,
        CorrelationID: correlationID,
        OccurredAt:    time.Now(),
    })
}

📖 Etkileşimli Dokümantasyon

OpenAPI 3.1 Spesifikasyonu

API şunlarla kapsamlı OpenAPI dokümantasyonu içerir:

/api/v1/funds/companies:
  get:
    tags:
      - Funds
    summary: Get All Portfolio Management Companies
    description: "Retrieves a list of all portfolio management companies with their codes and names"
    responses:
      "200":
        description: "Successful response"
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CompanyResponse"

Swagger UI Entegrasyonu

Çoklu endpoint'lerde mevcut etkileşimli dokümantasyon:

• Ana Dokümantasyon: http://localhost:8080/docs
• Swagger Yönlendirme: http://localhost:8080/swagger
• API Root: http://localhost:8080/

Özellikler:

• Canlı Test: Endpoint'leri doğrudan tarayıcıdan test etme
• İstek/Yanıt Örnekleri: Gerçek API çağrılarını görme
• Parametre Dokümantasyonu: Detaylı açıklamalar
• Kimlik Doğrulama Testi: Yerleşik auth desteği

📊 Performans Metrikleri

Yanıt Süreleri

• Şirket Verisi: < 10ms (bellekte)
• Önbellekli Fon Verisi: < 50ms
• Taze Fon Verisi: < 2s (scraping dahil)
• Rapor Üretimi: < 500ms

İş Hacmi

• Hız Sınırı: IP başına dakikada 100 istek
• Burst Kapasitesi: 20 istek
• Eşzamanlı Kullanıcılar: 1000+ desteklenir
• Önbellek İsabet Oranı: Normal operasyon sırasında %85+

Kaynak Kullanımı

• Bellek: ~50MB temel kullanım
• CPU: Normal yük sırasında < %5
• Redis: Tam önbellek için ~100MB
• Depolama: Loglar dahil < 1GB

🔮 Gelecek Geliştirmeler

Planlanan Özellikler

1. Gerçek Zamanlı WebSocket API: Canlı fon fiyat güncellemeleri
2. GraphQL Arayüzü: Esnek veri sorgulama
3. Makine Öğrenmesi: Fiyat tahmin modelleri
4. Mobil SDK: Native mobil uygulama entegrasyonu
5. Veri Dışa Aktarma: CSV, Excel, PDF rapor üretimi
6. Gelişmiş Analitics: Teknik göstergeler ve grafikler

Ölçeklenebilirlik Geliştirmeleri

1. Mikroservis Mimarisi: Özelleşmiş servislere bölme
2. Veritabanı Entegrasyonu: Geçmiş veriler için PostgreSQL
3. Mesaj Kuyrukları: Asenkron işleme için Redis Streams/RabbitMQ
4. Yük Dengeleme: Çoklu API instance'ları
5. CDN Entegrasyonu: Global içerik dağıtımı

💡 Öğrenilen Dersler

Teknik İçgörüler

1. Web Scraping Güvenilirliği: ChromeDP, dinamik içerik için yalnızca HTTP scraping'den daha güvenilir oldu
2. Önbellekleme Stratejisi: 30 dakika TTL, tazelik ve performans arasında optimal dengeyi sağladı
3. Hata İşleme: Kapsamlı hata yanıtları API kullanılabilirliğini önemli ölçüde iyileştirdi
4. Dokümantasyon: Etkileşimli Swagger UI kabul oranını dramatik şekilde artırdı

Go'ya Özel Öğrenmeler

1. Proje Yapısı: Standard Go Project Layout sürdürülebilirliği büyük ölçüde iyileştirdi
2. Interface Tasarımı: Küçük, odaklanmış interface'ler test etmeyi çok daha kolay hale getirdi
3. Context Kullanımı: Doğru context işleme timeout yönetimi için kritikti
4. Error Wrapping: Go 1.13+ error wrapping debugging'i önemli ölçüde iyileştirdi
5. Concurrency Yönetimi: Go'nun goroutine'leri ve kanal yapıları, yüksek verimli eşzamanlı işleme sağladı

🎉 Sonuç

TEFAS API'sini geliştirmek, finansal teknolojiye olan tutkumu Go'nun güçlü ekosistemi ile birleştiren inanılmaz bir yolculuk oldu. Proje, modern web scraping, akıllı önbellekleme ve temiz mimarinin kritik finansal verileri sunan üretime hazır bir API oluşturabileceğini gösteriyor.

Ana Başarılar:

• ✅ 50+ Portföy Yönetim Şirketi API üzerinden erişilebilir
• ✅ Kapsamlı Fon Verisi gerçek zamanlı güncellemelerle
• ✅ Üretime Hazır Mimari Docker deployment ile
• ✅ Etkileşimli Dokümantasyon Swagger UI ile
• ✅ Kurumsal Seviye Güvenlik hız sınırlama ve kimlik doğrulama ile
• ✅ Yüksek Performans Redis önbellekleme ve optimizasyonlarla

Etki & Kullanım

API şu alanlarda kullanılmaya başlandı:

• Finansal Uygulamalar: Portföy yönetim araçları
• Araştırma Platformları: Akademik finansal araştırmalar
• Trading Botları: Otomatik yatırım stratejileri
• Mobil Uygulamalar: Kişisel finans uygulamaları

Benimle İletişime Geçin ve API Kullanın

• Hızlı Başlangıç: API Dokümantasyonu
• GitHub: @serifcolakel
• LinkedIn: Serif Colakel
• Dev.to: @serifcolakel
• E-posta: [e-mail]

---

Okuduğunuz için teşekkürler! Bu makaleyi faydalı bulduysanız, lütfen beğenin ve Go, fintech ve yazılım mimarisi hakkında daha fazla içerik için beni takip etmeyi düşünün.

Etiketler: #golang #fintech #api #webscraping #redis #docker #swagger #türkiye #finans #tefas #yazılım #geliştirme