Döviz API Endpoint Dokümantasyonu

Bu doküman, Döviz API projesinin sunduğu endpoint'leri, kabul ettiği parametreleri ve örnek kullanımlarını detaylandırmaktadır.

Genel Bilgiler

• Base URL: API istekleri genellikle http://localhost:3000/api (geliştirme) veya https://api.siteadi.com/api (production) temel URL'si üzerinden yapılır.
• Veri Kaynağı: Veriler canlidoviz.com sitesinden çekilmektedir.
• Önbellekleme: İsteklerin çoğu sunucu tarafında 5 dakika (300 saniye) süreyle önbelleğe alınır.
• Yanıt Formatı: Tüm endpoint'ler JSON formatında yanıt döner. Hata durumlarında standart bir JSON hata nesnesi ({ error: "mesaj" }) ve uygun HTTP status kodu (404, 500 vb.) döndürülür.

Endpoint Detayları

1. Döviz Kurları (/api/doviz)

Tüm güncel döviz kurlarını veya belirtilen bir döviz kurunun detayını getirir.

• Method: GET
• Parametreler:
  • kod (string, opsiyonel): Belirli bir döviz kurunun detayını getirmek için kullanılır (örn: USD, EUR). Bu parametre verilmezse tüm döviz kurları listelenir.
• Başarılı Yanıt:
  • kod parametresi olmadan: DovizKuru[] (Döviz Kuru nesneleri dizisi)
  • kod parametresi ile: DovizDetay (Döviz Detay nesnesi)
• Örnek İstekler:
  • Tüm döviz kurları: /api/doviz
  • Amerikan Doları detayı: /api/doviz?kod=USD
• Not: DovizDetay nesnesi, DovizKuru nesnesinin tüm alanlarına ek olarak grafik verileri (grafikVerileri) ve diğer piyasalardaki (digerPiyasalar) fiyatları içerebilir.

2. Altın Fiyatları (/api/altin)

Serbest Piyasa veya Kapalı Çarşı'daki tüm altın fiyatlarını veya belirtilen bir altın türünün fiyatını getirir.

• Method: GET
• Parametreler:
  • piyasa (string, opsiyonel): Hangi piyasanın verisinin getirileceğini belirtir.
    • Değerler: serbest (varsayılan), kapali-carsi
  • kod (string, opsiyonel): Belirli bir altın türünün fiyatını getirmek için kullanılır (örn: GA - Gram Altın, C - Çeyrek Altın, XAU/USD - ONS Altın). Bu parametre verilmezse belirtilen piyasadaki tüm altın türleri listelenir.
• Başarılı Yanıt:
  • kod parametresi olmadan: AltinFiyati[] (Altın Fiyatı nesneleri dizisi)
  • kod parametresi ile: AltinFiyati (Tek bir Altın Fiyatı nesnesi)
• Örnek İstekler:
  • Tüm Serbest Piyasa altınları: /api/altin veya /api/altin?piyasa=serbest
  • Tüm Kapalı Çarşı altınları: /api/altin?piyasa=kapali-carsi
  • Serbest Piyasa Gram Altın: /api/altin?kod=GA veya /api/altin?piyasa=serbest&kod=GA
  • Kapalı Çarşı Gram Altın: /api/altin?piyasa=kapali-carsi&kod=GA
  • Serbest Piyasa ONS Altın: /api/altin?kod=XAU/USD

3. Kripto Paralar (/api/kripto)

Tüm güncel kripto para fiyatlarını veya belirtilen bir kripto paranın fiyatını getirir.

• Method: GET
• Parametreler:
  • kod (string, opsiyonel): Belirli bir kripto paranın fiyatını getirmek için kullanılır (örn: BTC, ETH). Bu parametre verilmezse tüm kripto paralar listelenir.
• Başarılı Yanıt:
  • kod parametresi olmadan: KriptoPara[] (Kripto Para nesneleri dizisi)
  • kod parametresi ile: KriptoPara (Tek bir Kripto Para nesnesi)
• Örnek İstekler:
  • Tüm kripto paralar: /api/kripto
  • Bitcoin fiyatı: /api/kripto?kod=BTC

4. Pariteler (/api/pariteler)

Tüm güncel pariteleri veya belirtilen bir pariteyi getirir.

• Method: GET
• Parametreler:
  • kod (string, opsiyonel): Belirli bir pariteyi getirmek için kullanılır. Kodlar / ile ayrılır (örn: EUR/USD, GBP/EUR). Bu parametre verilmezse tüm pariteler listelenir.
• Başarılı Yanıt:
  • kod parametresi olmadan: Pariteler[] (Parite nesneleri dizisi)
  • kod parametresi ile: Pariteler (Tek bir Parite nesnesi)
• Örnek İstekler:
  • Tüm pariteler: /api/pariteler
  • EUR/USD paritesi: /api/pariteler?kod=AUD-USD

5. Borsa Hisseleri (/api/borsa)

BIST'teki tüm hisse senetlerini veya belirtilen bir hisse senedinin güncel bilgilerini getirir.

• Method: GET
• Parametreler:
  • kod (string, opsiyonel): Belirli bir hisse senedini getirmek için BIST kodunu kullanın (örn: THYAO, GARAN). Bu parametre verilmezse tüm hisseler listelenir.
• Başarılı Yanıt:
  • kod parametresi olmadan: BorsaHisse[] (Borsa Hisse nesneleri dizisi)
  • kod parametresi ile: HisseDetay (Hisse Detay nesnesi)
• Örnek İstekler:
  • Tüm hisseler: /api/borsa
  • Türk Hava Yolları hissesi: /api/borsa?kod=THYAO
• Not: HisseDetay nesnesi, BorsaHisse nesnesinin tüm alanlarına ek olarak hacim, piyasa değeri, sektör gibi detayları içerir.

6. Emtialar (/api/emtia)

Tüm güncel emtia fiyatlarını veya belirtilen bir emtianın fiyatını getirir.

• Method: GET
• Parametreler:
  • kod (string, opsiyonel): Belirli bir emtiayı getirmek için kullanılır. Kodlar genellikle tire ile ayrılır (örn: ham-petrol, brent-petrol, gumus-spot-dolar). Bu parametre verilmezse tüm emtialar listelenir.
• Başarılı Yanıt:
  • kod parametresi olmadan: Emtia[] (Emtia nesneleri dizisi)
  • kod parametresi ile: Emtia (Tek bir Emtia nesnesi)
• Örnek İstekler:
  • Tüm emtialar: /api/emtia
  • Bakır: /api/emtia?kod=COPPER
  • Buğday: /api/emtia?kod=WHEAT

7. Endeksler (/api/endeks)

Tüm güncel borsa endekslerini veya belirtilen bir endeksi getirir.

• Method: GET
• Parametreler:
  • kod (string, opsiyonel): Belirli bir endeksi getirmek için kullanılır (örn: XU100, DXY, SPX). Bu parametre verilmezse tüm endeksler listelenir.
• Başarılı Yanıt:
  • kod parametresi olmadan: Endeks[] (Endeks nesneleri dizisi)
  • kod parametresi ile: Endeks (Tek bir Endeks nesnesi)
• Örnek İstekler:
  • Tüm endeksler: /api/endeks
  • BIST 100: /api/endeks?kod=XU100
  • Dolar Endeksi: /api/endeks?kod=DXY

8. Grafik Verileri (/api/grafik) - Varsa

Not: Bu endpoint'in varlığı scraper.ts dosyasındaki fetchGrafikVerileri fonksiyonuna bağlıdır. Eğer bu fonksiyon aktif olarak kullanılmıyorsa, bu endpoint çalışmayabilir.

Belirtilen bir finansal varlık (döviz, altın, kripto, hisse vb.) için belirli bir periyottaki grafik verilerini (OHLC - Açılış, Yüksek, Düşük, Kapanış) getirir.

• Method: GET
• Parametreler:
  • kod (string, zorunlu): Grafik verisi istenen varlığın kodu (örn: USD, GA, BTC, THYAO).
  • piyasa (string, opsiyonel): Altın için piyasayı belirtir (serbest, kapali-carsi). Diğer varlıklar için genellikle gerekli değildir.
  • periyot (string, opsiyonel): İstenen zaman periyodu. Varsayılan '1d' (1 gün).
    • Olası değerler: 1h, 1d, 1w, 1m, 3m, 6m, 1y, 5y, all
• Başarılı Yanıt: GrafikVerisi[] (Grafik Verisi nesneleri dizisi)
• Örnek İstekler:
  • Dolar için 1 günlük grafik: /api/grafik?kod=USD veya /api/grafik?kod=USD&periyot=1d
  • Kapalı Çarşı Gram Altın için 1 aylık grafik: /api/grafik?kod=GA&piyasa=kapali-carsi&periyot=1m
  • Bitcoin için 1 haftalık grafik: /api/grafik?kod=BTC&periyot=1w
  • THYAO hissesi için tüm zamanlar grafiği: /api/grafik?kod=THYAO&periyot=all

Bu doküman, API'nin mevcut durumunu yansıtmaktadır. Yeni endpoint'ler eklendikçe veya mevcutlar değiştikçe güncellenmelidir.