Cevap Bloğu
ONEPiR Kur API nedir? ONEPiR Kur API’si, e-ticaret geliştiricilerinin ve işletmelerin altın ile döviz kurlarını JSON formatında alıp kendi sistemlerinde kullanmasını sağlayan REST tabanlı bir servistir. Veriler TCMB ve finans sağlayıcılarından çekilir; günlük ve aylık ortalama değerler de sunulur.
API NEDİR VE NEDEN ÖNEMLİDİR?
API (Application Programming Interface), yazılım sistemlerinin birbirleriyle veri alışverişi yapmasını sağlayan arayüzdür. E-ticarette kur verisi, ürün fiyatlandırma, kampanya hesaplama ve raporlama için kritiktir. Kendi API’si olmayan firmalar genelde manuel veri girişi veya Excel tablolarına bağımlı kalır.
TCMB’nin resmi verileri günlük bazda yayınlanır. E-ticaret sitelerinde anlık veya saatlik güncelleme gerektiğinde ek kaynaklar devreye girer. ONEPiR API, bu kaynakları toplar ve tek endpoint üzerinden sunar.
ONEPiR Kur Apı Özellikleri
JSON Veri Formatı Örneği: API yanıtı standart JSON yapısındadır. Örnek yapı şöyle olabilir: Kurlar nesnesi altında hasAltin, gramAltin, dolar, euro gibi anahtarlar; her biri alis ve satis değerleri içerir. Tarih ve zaman damgası metadata olarak eklenir.
Güncelleme sıklığı kullanıcı tarafından seçilebilir. Anlık modda veriler saniyeler içinde yenilenir. Saatlik veya günlük modda sunucu yükü azalır. Günlük ve aylık ortalama değerler ayrı endpoint’lerde sunulur.
API Nasıl Bağlanır? Entegrasyon Adımları
Adım 1: ONEPiR.com üzerinden ücretsiz kayıt oluşturun ve API anahtarı alın.
Adım 2: Dokümantasyondaki base URL ve endpoint yapısını inceleyin.
Adım 3: HTTP GET isteği ile authentication header’ını (ör. x-api-key veya Authorization) gönderin.
Adım 4: JSON yanıtını parse edip uygulamanızda kullanın.
Node.js örneği: fetch veya axios ile base URL’e istek atılır, response.json() ile veri alınır. Python’da requests kütüphanesi kullanılabilir. cURL ile test için: curl -H “Authorization: Bearer API_KEY” https://api.ONEPiR.com/currency şeklinde çağrı yapılabilir.
Kullanım Senaryoları
Ürün fiyatlama: API’den çekilen kur, stok maliyeti veya hammadde fiyatı ile çarpılarak satış fiyatı hesaplanır. Kuyumcu sitelerinde gram altın kuru gramaj ile çarpılır, işçilik eklenir.
Banner gösterimi: Sitede “Güncel dolar kuru: 43.50 TL” şeklinde dinamik banner’lar gösterilebilir. Cache ile istek sayısı azaltılır.
Raporlama: Günlük ortalama kurlar, muhasebe ve finans raporlarında kullanılabilir. Excel veya BI araçlarına veri aktarımı yapılabilir.
Performans, Güncelleme Sıklığı Ve Veri Kaynağı
Veriler TCMB, döviz büroları ve global finans sağlayıcılarından türetilir. Anlık modda güncelleme saniyeler mertebesindedir. Rate limit politikası vardır; aşımda HTTP 429 döner. Dokümantasyonda dakikada veya günde maksimum istek sayısı belirtilir.
Caching önerilir. Aynı kur verisi kısa sürede tekrar kullanılacaksa yerel cache ile API çağrısı azaltılır. Bu hem performans hem rate limit açısından faydalıdır.
Kur Apı Karşılaştırma Tablosu
| Özellik | ONEPiR API | TCMB Açık Veri | Manuel Kaynak |
|---|---|---|---|
| Format | JSON | XML/CSV | Excel |
| Güncelleme | Anlık/Saatlik Günlük | Manuel | |
| Altın kurları | Var | Sınırlı | Değişken |
| Auth gerekli | Evet | Hayır | Hayır |
| Rate limit | Var | Yok | Yok |
| Dokümantasyon | Var | Var | Yok |
Entegrasyon Kontrol Listesi
1. API anahtarı alındı mı?
2. Base URL ve endpoint bilgileri dokümantasyondan doğrulandı mı?
3. Authentication header’ı doğru formatta gönderiliyor mu?
4. Hata durumunda (401, 429, 500) retry veya fallback mekanizması var mı?
5. Rate limit aşılmaması için cache veya throttle uygulandı mı?
6. JSON parse hataları try-catch ile yakalanıyor mu?
Uygulama Notları
Yüksek trafikli sitelerde her sayfa yüklemesinde API çağrısı yapmak uygun değildir. Cache süresi 5 ila 60 dakika arası seçilebilir. Kur borsa saatleri dışında değişim düşük olduğundan gece cache süresi uzatılabilir.
Alternatif olarak sadece admin panelinde veya arka planda cron job ile veri çekip veritabanına yazan bir mimari tercih edilebilir. Bu durumda API rate limit daha az baskı altında kalır.
Sıkça Sorulan Sorular
ONEPiR Kur API’sine nasıl erişilir?
ONEPiR.com üzerinden ücretsiz kayıt oluşturulur. Panelden API anahtarı alınır. Dokümantasyondaki base URL ve endpoint’lere HTTP GET ile istek atılır. Authorization header’ında anahtar gönderilir.
JSON yanıt örneği nedir?
Yanıt, kurlar nesnesi içinde hasAltin, gramAltin, dolar, euro gibi anahtarlar ve her biri için alis, satis değerleri içerir. Tarih ve zaman damgası metadata olarak eklenir. Örnek yapı dokümantasyonda bulunur.
API kullanımında rate limit var mı?
Evet. Dakikada veya günde maksimum istek sayısı vardır. Aşımda HTTP 429 dönülür. Yüksek trafik için cache kullanımı önerilir.
API ücretsiz mi?
Modüller ücretsizdir. API çağrıları kontör tüketir. Hediye kontör ile başlangıç yapılır. Detaylar ONEPiR.com fiyatlandırma sayfasında yer alır.
Hangi kurlar desteklenir?
Has altın, gram altın, 14 ayar, 22 ayar, dolar, euro ve gümüş USD gibi kurlar sunulur. Liste platform güncellemeleriyle genişleyebilir.
Günlük ve aylık ortalama nasıl alınır?
Ayrı endpoint’ler veya parametreler ile günlük ve aylık ortalama değerler çekilebilir. Muhasebe ve raporlama amaçlı kullanım için uygundur.
Özet Ve Aksiyon Çağrısı
ONEPiR Kur API’si, e-ticaret sitelerinin kur verisini merkezi ve güncel şekilde almasını sağlar. JSON formatı, Node.js, Python ve diğer dillerde kolay entegrasyona imkân verir.
Apı İle Ürün Fiyatlama Akışı
Kur verisi alındıktan sonra fiyat hesaplama şu formüle dayanır: Satış fiyatı eşittir (birim maliyet çarpı kur) artı kâr marjı. Kuyumculukta gram fiyatı çarpı gramaj artı işçilik bedeli uygulanır. ONEPiR panelinde bu kurallar görsel olarak tanımlanır; API kullanan geliştiriciler aynı mantığı kendi kodlarında uygular.
Hata yönetimi kritiktir. API yanıt vermezse veya geçersiz veri dönerse önceki cache değeri kullanılmalıdır. Fallback mekanizması olmayan sistemlerde boş veya hatalı fiyat gösterimi müşteri güvenini zedeler. Timeout süresi 5 ila 10 saniye arası önerilir.
Güvenlik Ve Veri Gizliliği
API anahtarı asla istemci tarafında (JavaScript, mobil uygulama) açıkta bırakılmamalıdır. Sunucu taraflı proxy veya backend çağrısı zorunludur. Anahtar sızıntısı durumunda panelden yeni anahtar üretilir, eskisi iptal edilir.
Veri iletimi HTTPS üzerinden yapılır. TLS 1.2 veya üzeri desteklenir. Kurlar genel finans verisi olduğundan KVKK kapsamında kişisel veri işlenmez; ancak erişim logları tutulabilir.
Node.js Ve Python Örnek Kodları
Node.js: const response = await fetch(baseUrl, { headers: { Authorization: Bearer + apiKey } }); const data = await response.json(); if (data.kurlar) { const dolar = data.kurlar.dolar.satis; }
Python: import requests; r = requests.get(base_url, headers={“Authorization”: “Bearer ” + api_key}); data = r.json(); dolar = data.get(“kurlar”, {}).get(“dolar”, {}).get(“satis”)
Gerçek endpoint ve parametreler ONEPiR.com dokümantasyonundan alınmalıdır. Yukarıdaki örnekler yapısal kullanım içindir.
Ne Zaman Apı Kullanılmamalı
Sadece panel üzerinden fiyat güncellemesi yapan, ek geliştirme yapmayan kullanıcılar API’ye ihtiyaç duymaz. ikas entegrasyonu kurulu olan mağazalar zaten ONEPiR panelinden fiyatları yönetir. API, özel yazılım, raporlama veya çoklu kanal senaryolarında anlamlıdır.