Özet: Fintech panolarında, ERP kapanışlarında ve denetim dosyalarında çoğu ekip hâlâ “o günkü kuru” Excel’den veya TCMB sitesinden elle kopyalar. Fatura tarihi ile kapanış tarihi farklıysa kur farkı yanlış hesaplanır; hafta sonu ve tatil günlerinde boş hücre kalır; beş yıllık grafik için onlarca XML dosyası indirilir. Bu yazıda apibir Geçmiş Döviz Kurları API ile tek gün, tarih aralığı ve dönemsel ortalama kurları Node.js / Python’da çekmeyi, kur farkı otomasyonu kurmayı ve Chart.js için zaman serisi üretmeyi anlatıyoruz.
İçindekiler
- Neden geçmiş kurları API ile çekmelisiniz?
- Uç noktalar ve parametreler
- Tek güne ait TCMB kurunu çekmek
- Zaman serisi ve grafik formatı
Canlı kur ekranı “şimdi ne?” sorusunu cevaplar. Muhasebe, faturalama ve geriye dönük analiz ise “o tarihte neydi?” sorusuna ihtiyaç duyar. Manuel arşivlemenin tipik kırılmaları:
- Eksik gün: Hafta sonu ve resmi tatilde TCMB bülteni yoktur; boş satır veya yanlış doldurma üretir.
- Kur farkı hatası: Fatura tarihi ile tahsilat/kapanış tarihi için farklı kurlar gerekir; tek hücreyle yetinmek farkı sıfırlar.
- Ölçek: Beş yıllık USD/EUR serisi için dosya birleştirmek yerine tek REST çağrısı yeterlidir.
API tabanlı kurgu üçünü birden çözer: tarih anahtarlı sözlük, tatil/hafta sonu için meta.missingDays bilgisi ve grafik kütüphanelerine uygun series formatı.
Uç Noktalar ve Parametreler
Temel adres: https://api.apibir.com/v1
Yanıt zarfı diğer servislerle ortaktır: success, data, creditsUsed, creditsRemaining. Uzun zaman serilerinde kredi tüketimi dokümantasyondaki tabloya göre artabilir (90 güne kadar 2, üzeri için kademeli).
Önemli sorgu parametreleri
| Uç | Ne döner |
|---|
| Parametre | Örnek | Açıklama |
|---|---|---|
date |
2024-03-15 |
Tek gün sorgusu |
start / end |
2026-07-01 |
Zaman serisi aralığı (dahil) |
symbols |
USD,EUR,GBP |
Para birimi filtresi |
format |
object veya series |
Sözlük veya grafik dizisi |
async function kurOGunu(date, symbols = "USD,EUR") {
const url = new URL("https://api.apibir.com/v1/fx/history");
url.searchParams.set("date", date);
url.searchParams.set("symbols", symbols);
const res = await fetch(url, {
headers: { authorization: `apikey ${process.env.APIBIR_KEY}` }
});
if (!res.ok) throw new Error(`apibir ${res.status}`);
const payload = await res.json();
return payload.data;
}
const gun = await kurOGunu("2026-08-07");
console.log(gun);
Python
import os, requests
HEADERS = {"authorization": f"apikey {os.environ['APIBIR_KEY']}"}
def fx_history(date, symbols="USD,EUR"):
r = requests.get(
"https://api.apibir.com/v1/fx/history",
params={"date": date, "symbols": symbols},
headers=HEADERS,
timeout=10,
)
r.raise_for_status()
return r.json()["data"]
print(fx_history("2026-08-07"))
Örnek yanıt iskeleti (dokümantasyondaki şemaya uygun):
{
"success": true,
"creditsUsed": 1,
"base": "TRY",
İstenen gün tatil veya hafta sonuysa meta.missingDays dolabilir; ürün kuralınızda bir önceki iş günü kurunu kullanıp kullanmayacağınızı netleştirin.
2. Adım: Zaman Serisi ve Grafik Formatı
Aylık / yıllık grafik veya backtest için /fx/timeseries kullanın. Chart.js’e doğrudan vermek için format=series tercih edin.
curl --request GET \
--url "https://api.apibir.com/v1/fx/timeseries?start=2026-07-01&end=2026-07-31&symbols=USD&format=series" \
--header "authorization: apikey APIBIR-8f2c...9d41"
async function usdSerisi(start, end) {
const url = new URL("https://api.apibir.com/v1/fx/timeseries");
url.searchParams.set("start", start);
url.searchParams.set("end", end);
url.searchParams.set("symbols", "USD");
url.searchParams.set("format", "series");
def fx_timeseries(start, end, symbols="USD,EUR", fmt="object"):
r = requests.get(
"https://api.apibir.com/v1/fx/timeseries",
params={"start": start, "end": end, "symbols": symbols, "format": fmt},
headers=HEADERS,
timeout=15,
)
r.raise_for_status()
return r.json()
payload = fx_timeseries("2026-07-01", "2026-07-05")
print(payload["start"], payload["end"], payload.get("meta"))
Uzun aralıklarda her sayfa yüklemesinde API’ye gitmeyin: seriyi kendi veritabanınıza yazıp panoyu oradan besleyin; ETag / If-None-Match ile değişmeyen yanıtları 0 kredide tutun.
3. Adım: Dönemsel Ortalama Kur
Sözleşme maddelerinde “aylık ortalama TCMB satış kuru” gibi ifadeler sık görülür. /fx/average bu hesabı sunucu tarafında üretir.
def aylik_ortalama(year_month, symbols="USD"):
Ortalama tanımını (alış mı satış mı, iş günü mü takvim günü mü) ürün dokümanınızda sabitleyin; API’den gelen alan adlarıyla birebir eşleştirin.
4. Adım: Kur Farkı ve Dönem Sonu Değerleme
Tipik muhasebe senaryosu: fatura tarihinde kayda alınan dövizli tutar, ay/yıl sonunda yeniden değerlenir.
def kur_farki(tutar_usd, fatura_tarihi, kapanis_tarihi):
fatura = fx_history(fatura_tarihi, "USD")
kapanis = fx_history(kapanis_tarihi, "USD")
kur1 = fatura[fatura_tarihi]["USD"]
kur2 = kapanis[kapanis_tarihi]["USD"]
tl1 = tutar_usd * kur1
tl2 = tutar_usd * kur2
return {
"fatura_tl": round(tl1, 2),
"kapanis_tl": round(tl2, 2),
"fark_tl": round(tl2 - tl1, 2),
Geçmiş kur “o gün neydi?” sorusunu cevaplar; “şimdi ne?” sorusu Döviz Kurları API (/fx/latest) ile gelir. Tipik ürün kuralları:
- Fatura oluşturma → fatura tarihine
/fx/history - Anlık gösterge / çevirici →
/fx/latest - İş günü filtreleme → Resmi Tatiller & İş Günü API
- Kur hareketi + makro olay → Ekonomik Takvim API ile çapraz okuma
async function faturaKurKarti(invoiceDate) {
const hist = await kurOGunu(invoiceDate, "USD,EUR");
const live = await fetch("https://api.apibir.com/v1/fx/latest?symbols=USD,EUR", {
headers: { authorization: `apikey ${process.env.APIBIR_KEY}` }
}).then((r) => r.json());
return { invoice: hist, live: live.data };
}
Canlı kur entegrasyonu için mevcut rehberimize bakın: TCMB ve Serbest Piyasa Döviz Kurlarını Node.js & Python ile Çekme.
Sık Yapılan Entegrasyon Hataları
Sık Sorulan Sorular
Veriler hangi kaynaktan geliyor?
Geçmiş döviz uçları TCMB bülteni sonrası günlük kapanışları sunar; yanıtta source: "tcmb" görünür. Güncelleme saati tipik olarak 15:30 (Europe/Istanbul) sonrasıdır.
Ne kadar geriye gidebilirim?
Ürün sayfasında belirtilen arşiv yaklaşık 30 yıllık tarihsel kurları kapsar. Çok uzun aralıklarda kredi tüketimi artar; gerektiğinde yılı parçalayarak çekin.
/fx/history ile /fx/timeseries farkı nedir?
history tek gün (veya dar kullanım) için; timeseries aralık ve grafik/analiz için tasarlanmıştır. Ortalama için /fx/average kullanın.
Kod yazmadan tarihsel kur raporu alabilir miyim?
Evet. Kurumsal kur ve muhasebe otomasyonu için günlük TCMB kapanışlarını ERP / e-posta bültenine aktaran hizmetler mevcuttur. Kapsam için hizmetler ve teklif formuna bakın.
Başlamak için: Ücretsiz plan 100 kredi/ay ile geliştirme ve deneme için yeterlidir. Uç noktaların tamamı Geçmiş Döviz Kurları API sayfasında; kimlik doğrulama, kredi tablosu ve hata kodları dokümantasyonda yer alır.
| Hata | Sonucu | Doğrusu |
|---|---|---|
| Her sayfa yüklemesinde 5 yıllık seri çekmek | Kredi ve gecikme şişer | Seriyi önbelleğe / DB’ye yazın; ETag kullanın |
| Tatil gününü “veri yok” sanıp hataya düşmek | Kapanış job’ı kırılır | meta.missingDays ve iş günü kuralını uygulayın |
| Canlı kuru fatura tarihine yazmak | Denetimde uyumsuzluk | Fatura günü için /fx/history |
start/end formatını GG-AA-YYYY vermek |
invalid_parameter |
ISO YYYY-MM-DD kullanın |
"kur1": kur1,
"kur2": kur2,
}
print(kur_farki(10000, "2026-07-01", "2026-07-31"))
ERP’ye yazmadan önce source alanının tcmb olduğunu doğrulayın; serbest piyasa kuru muhasebe kaydı için uygun olmayabilir.
5. Adım: Canlı Kur API’siyle Birlikte Kullanım
# year_month örn. 2026-07
r = requests.get(
"https://api.apibir.com/v1/fx/average",
params={"period": year_month, "symbols": symbols},
headers=HEADERS,
timeout=10,
)
r.raise_for_status()
return r.json()["data"]
const res = await fetch(url, {
headers: { authorization: `apikey ${process.env.APIBIR_KEY}` }
});
if (!res.ok) throw new Error(`apibir ${res.status}`);
const { data } = await res.json();
// data: [{ date, USD }, ...] — labels/datasets üretmek kolay
return data;
}
"source": "tcmb",
"data": {
"2026-08-07": { "USD": 41.1287, "EUR": 48.1120 }
},
"meta": {
"days": 1,
"missingDays": []
}
}
1. Adım: Tek Güne Ait TCMB Kurunu Çekmek
Fatura veya sözleşme tarihindeki resmi kur için /fx/history yeterlidir.
cURL
curl --request GET \
--url "https://api.apibir.com/v1/fx/history?date=2026-08-07&symbols=USD,EUR" \
--header "authorization: apikey APIBIR-8f2c...9d41" \
--header "accept: application/json"
Node.js (fetch)
GET /fx/history
- Belirli bir tarihin kurları
GET /fx/timeseries
- Tarih aralığı zaman serisi
GET /fx/average
- Dönemsel ortalama kur (aylık/yıllık)
Kimlik doğrulama tüm apibir uçlarında aynıdır:
Authorization: apikey APIBIR-8f2c...9d41
Accept: application/json
- Dönemsel ortalama kur
- Kur farkı ve dönem sonu değerleme
- Canlı kur API’siyle birlikte kullanım
- Sık yapılan hatalar
- Sık sorulan sorular