API Key ve Authorization Header
Modern bir fiyat API'sinde kimlik her istekle birlikte, gövdede veya URL'de değil, HTTP başlığında taşınır. Uygulamanızın panelden aldığı API key'i her isteğe `Authorization: Bearer <API_KEY>` biçiminde eklemeniz beklenir. Aynı anahtar x-api-key başlığıyla da gönderilebilir. Anahtarı URL'nin query string'ine koymak, sunucu erişim loglarına ve tarayıcı geçmişine sızmasına yol açtığı için önerilmez; başlık ekleyebildiğiniz her durumda header tercih edin. Yalnızca WebSocket bağlantısında başlık gönderilemediği için anahtar adresteki token parametresiyle iletilir.
API key'i istemci tarafı JavaScript içinde açıkta bırakmamak kritik önemdedir. Anahtarı sunucu tarafında bir ortam değişkeninde (environment variable) saklayın ve tarayıcıdan gelen çağrıları kendi backend'iniz üzerinden proxy'leyin. Böylece hem anahtar gizli kalır hem de rate limit ve önbellekleme mantığını tek noktada yönetirsiniz.
Anahtar döndürme (rotation) için genellikle birden fazla aktif anahtar tanımlanabilir. Yeni anahtarı devreye alıp eskisini bir süre çift çalıştırdıktan sonra iptal etmek, kesintisiz geçiş sağlar. Anahtar sızması şüphesinde ilk yapılacak iş, ilgili anahtarı panelden anında iptal edip yerine yenisini üretmektir.
HTTP Hata Kodları ve Anlamları
Kimlik doğrulama başarısız olduğunda 401 Unauthorized alırsınız; yanıttaki reason alanı nedenini makine okunur biçimde söyler: no_key (anahtar gönderilmedi), invalid_key (anahtar geçersiz ya da pasif) veya no_active_subscription (aktif paket ya da deneme süresi yok). no_key ve invalid_key için anahtarı ve header biçimini, no_active_subscription için paket durumunuzu kontrol edin; paket yenilendikten sonra erişim en geç bir dakika içinde açılır.
`429 Too Many Requests`, Hasfiyat API'de aylık REST istek kotanızın dolduğu anlamına gelir; yanıtta reason alanı quota_exceeded olur ve X-Api-Quota: exceeded başlığı eklenir. Kota yeni dönemde yenilendiği ya da paket yükseltmesiyle arttığı için aynı isteği hemen tekrarlamak sonucu değiştirmez; isteklerinizi seyreltin ya da sürekli güncellemeyi WebSocket'e taşıyın. Sunucu kaynaklı `500` hatalarında ise istek sizin tarafınızda hatalı değildir; kısa bir bekleme sonrası tekrar denemek doğru yaklaşımdır.
Örnek bir hata yanıtı tutarlı bir JSON yapısı taşır: `{ "error": "API anahtarı gönderilmedi. İsteğe Authorization: Bearer <anahtar> veya x-api-key başlığı ekleyin.", "reason": "no_key", "clientIp": "203.0.113.10", "domain": null }`. error alanı kullanıcıya gösterilebilecek açıklamayı, reason ise kodunuzda karar vermek için kullanacağınız sabit değeri taşır; hata işleyicinizi reason alanına göre yazmak en sağlam yoldur.
Kota, Toplu Sorgu ve Zaman Damgası
Kota yönetimini yalnızca 429'a tepki vererek değil, proaktif olarak da yapmalısınız. Hasfiyat API'de REST istekleri aylık kotayla sayılır; güncel kullanımınızı ve kotanızı panelden izlersiniz. Anlık fiyat için sürekli sorgulamak yerine WebSocket akışı kullanmak hem gecikmeyi hem de istek sayısını dramatik biçimde düşürür; WebSocket akışı REST kotasından düşmez.
Hasfiyat API'de sayfalama yoktur; anlık fiyat ucu seçtiğiniz kaynağın tüm kalemlerini tek yanıtta döndürür, symbols parametresiyle de yalnızca ihtiyacınız olanları alırsınız. Tarihsel veri ucunda tek istekte en fazla 366 günlük (günlük bar) ya da 31 günlük (saatlik bar) aralık döner; daha uzun dönemleri from ve to parametreleriyle pencerelere bölerek çekersiniz.
Fiyat verisinde zaman damgası kritik bir alandır. Hasfiyat API zamanı kalem bazında değil yanıt bazında verir: lastUpdate alanı UTC bazlı ISO 8601 biçimindedir (`2026-10-25T20:26:17.553Z`), dataAgeMs ise verinin kaç milisaniye önce tazelendiğini gösterir. İki farklı kaynağı karşılaştırırken saat dilimi karışıklığına düşmemek için verileri her zaman UTC'de saklayıp yalnızca gösterim anında yerel saate çevirin. Örnek yanıt: `{ "source": "harem", "count": 1, "data": [{ "title": "HAS ALTIN", "buy": "6.421,99", "sell": "6.452,21" }], "dataAgeMs": 549, "stale": false, "lastUpdate": "2026-10-25T20:26:17.553Z" }`.
Hasfiyat API'si bu rehberdeki temel davranışları standart olarak sunar: Authorization header ile kimlik doğrulama, reason alanlı tutarlı hata JSON'ları, aylık kota bilgisi ve yanıt bazlı zaman damgaları. Sembolleri REST ve WebSocket üzerinden, kaynaklar arasında failover ile aldığınız için bu desenleri doğrudan üretime taşıyabilirsiniz.
Sık sorulan sorular
Hasfiyat API'sinde kimlik doğrulama nasıl yapılır?
Her istekte API anahtarınızı Authorization header'ı içinde göndererek kimliğinizi doğrularsınız. Anahtar hesabınıza özeldir ve tüm REST çağrılarında gereklidir. WebSocket bağlantısında ise aynı anahtar bağlantı adresindeki token parametresiyle iletilir.
API anahtarımı nereden alırım?
API anahtarınız Hasfiyat hesabınıza tanımlanır ve panel üzerinden erişebileceğiniz kimlik bilgisidir. Anahtarı her istekte Authorization header'ında göndererek yetkili çağrı yaparsınız. Anahtarınızı gizli tutun ve istemci koduna gömmekten kaçının.
API anahtarını URL'ye mi yoksa header'a mı koymalıyım?
Anahtar Authorization header'ı içinde gönderilmelidir; URL'ye ya da query parametresine koymak güvenlik açısından risklidir çünkü loglara ve tarayıcı geçmişine düşer. Header yöntemi anahtarı istek gövdesinden ayrı, güvenli biçimde iletir. Bu nedenle tüm örnekler header kullanır.
API anahtarım sızarsa ne yapmalıyım?
Anahtarın sızdığından şüpheleniyorsanız panel üzerinden anahtarı yenileyip eski anahtarı geçersiz kılmalısınız. Ardından tüm entegrasyonlarınızdaki Authorization değerini yeni anahtarla güncelleyin. Anahtarı istemci tarafı koda gömmemek bu riski baştan azaltır.
Tek anahtarla hem REST hem WebSocket kullanabilir miyim?
Evet, aynı API anahtarı hem REST isteklerinde Authorization header'ı olarak hem de WebSocket bağlantısında token parametresi olarak kullanılır. Böylece tek anahtarla hem anlık sorgu hem canlı akış senaryolarını yönetirsiniz. Webhook yapılandırması da aynı hesap üzerinden tanımlanır.
401 hatası aldım, nedenini nasıl anlarım?
Yanıt gövdesindeki reason alanına bakın: no_key anahtarın hiç gönderilmediğini, invalid_key anahtarın geçersiz ya da pasif olduğunu, no_active_subscription ise hesabınızda aktif paket ya da deneme süresi bulunmadığını gösterir. İlk ikisinde header'ı ve anahtarı, üçüncüsünde paket durumunuzu kontrol edin.
429 Too Many Requests hatası ne anlama gelir?
Hasfiyat API'de 429, aylık REST istek kotanızın dolduğunu gösterir; gövdedeki reason alanı quota_exceeded olur. Kota yeni dönemde yenilenir ya da paketinizi yükselterek artar; aynı isteği hemen tekrarlamak sonucu değiştirmez. Sık anlık veri gerekiyorsa tekrarlı REST sorgusu yerine WebSocket akışına geçmek kota baskısını kaldırır.
Rate-limit aşımını nasıl önlerim?
İstek sıklığınızı ihtiyacınıza göre düşürüp sonuçları kısa süreli önbelleğe alarak gereksiz çağrıları azaltırsınız. Canlı fiyat için REST döngüsü yerine WebSocket kullanmak en etkili yöntemdir çünkü veri push edilir. Ayrıca 429 aldığınızda üstel geri çekilme uygulayın.
429 aldıktan sonra ne yapmalıyım?
429 aylık kotanın dolduğunu gösterdiği için kısa beklemeler sonucu değiştirmez. İsteklerinizi durdurup panelden kullanımınızı kontrol edin; yeni dönemi bekleyebilir ya da paketinizi yükseltebilirsiniz. Anlık ihtiyaç yüksekse WebSocket'e geçmek, kotanızı tüketmeden güncel fiyat almanızı sağlar.
Çok sayıda sembolü sık sık çekmem gerekiyor, limiti aşmadan nasıl yaparım?
Tek istekte çoklu sembol desteğini kullanarak birçok ürünü bir çağrıda alırsınız; bu istek sayısını ciddi biçimde azaltır. Sürekli güncelleme için WebSocket akışıyla kaynağın tüm sembollerini tek bağlantı üzerinden dinlersiniz. Böylece 429 riskini en aza indirirsiniz.
WebSocket kullanınca rate-limit tamamen kalkar mı?
WebSocket akışı aylık REST istek kotanızdan düşmez; tek bağlantı üzerinden sürekli güncel fiyat aldığınız için REST çağrı sayınız çok azalır. Bağlantı için aktif paket ya da deneme süresi gerekir; paketiniz biterse bağlantı kapatılır.
API'den 500 hatası alıyorum, ne yapmalıyım?
500 Internal Server Error sunucu tarafında geçici bir sorun olduğunu gösterir ve genelde istemci hatası değildir. Kısa bir bekleme sonrası isteği yeniden denemeniz önerilir. Çoklu-kaynak failover birçok kaynak sorununu otomatik telafi etse de anlık sunucu hataları geçici olabilir.
401, 429 ve 500 hataları arasındaki fark nedir?
401 kimlik doğrulanamadı (anahtar eksik, geçersiz ya da aktif paket yok), 429 aylık REST kotası doldu, 500 ise sunucu tarafında beklenmeyen bir hata anlamına gelir. 401 ve 429 hesap tarafında çözülür; anahtarınızı ve paket durumunuzu kontrol edin. 500'de ise kısa bir süre bekleyip yeniden deneyin.
Hangi durumda 400 Bad Request alırım?
400, tarihsel veri ucunda eksik ya da geçersiz parametre gönderdiğinizde döner: symbol parametresi yoksa, period 1d ya da 1h dışında bir değerse, from tarihi to tarihinden sonraysa veya harem dışında bir kaynak istenmişse. Anlık fiyat ucunda tanınmayan bir sembol hata vermez, yalnızca yanıta eklenmez; tek sembol ucunda ise 404 döner.
API hatalarını uygulamamda nasıl sağlıklı yönetirim?
Yanıtın durum kodunu her zaman kontrol edip 401 için anahtar ve paket kontrolü, 429 için istekleri durdurma, 500 için kısa beklemeyle yeniden deneme mantığı uygulayın. Hataları kullanıcıya anlaşılır mesajlarla gösterip logladığınızda sorunları hızlı teşhis edersiniz. Kritik akışlarda yeniden deneme ve zaman aşımı stratejisi bulundurun.
Başarılı bir istekte hangi durum kodunu beklemeliyim?
Başarılı fiyat sorgularında HTTP 200 OK durum kodu ve gövdede JSON fiyat verisi dönmesini beklersiniz. Uygulamanızda önce 200 kontrolü yapıp sonra gövdeyi çözmeniz sağlıklıdır. 200 dışı kodlarda ilgili hata yönetimi devreye girmelidir.
Bir veri kaynağı çökerse fiyat alamaz mıyım?
Hayır, Hasfiyat veri kaynakları ve çoklu-kaynak failover mimarisi kullanır; bir kaynak düşerse fiyat başka kaynaktan sağlanır. Bu sayede kesinti riski önemli ölçüde azalır ve süreklilik korunur. Yine de anlık sunucu hatalarına karşı istemci tarafında yeniden deneme eklemeniz iyidir.
Çok sayıda sembolü listelerken sayfalama gerekir mi?
Hayır. Anlık fiyat ucu seçtiğiniz kaynağın tüm kalemlerini tek yanıtta döndürür; yanıt küçük olduğu için sayfalama yoktur. Yalnızca bazı kalemlere ihtiyacınız varsa symbols parametresiyle bunları isteyerek yanıtı daha da küçültebilirsiniz.
Tüm kalemleri aldığımı nasıl anlarım?
Yanıttaki count alanı dönen kalem sayısını gösterir ve data listesinin uzunluğuna eşittir. Sayfalama olmadığı için tek yanıt seçtiğiniz kaynağın tüm kalemlerini içerir; ek bir sayfa isteği gerekmez.
Sadece ihtiyacım olan sembolleri nasıl çekerim?
İsteğe symbols parametresiyle virgülle ayrılmış sembol adlarını eklersiniz (ör. symbols=HAS ALTIN,USD/TL); yanıt yalnızca bu kalemleri içerir. Tek bir kalem için /api/prices/{sembol} ucunu da kullanabilirsiniz. Hedefli sorgu hem yanıtı küçültür hem hızlandırır.
Sık sorgu yaparsam kotaya takılır mıyım?
Her REST isteği aylık kotanızdan düşer; çok sık sorgu kotayı hızla tüketir ve kota dolduğunda 429 alırsınız. Kısa süreli önbellek kullanmak ve sürekli güncel fiyat için WebSocket'e geçmek bunu önler. Mümkünse hedefli sorgularla toplam istek sayısını düşürün.
API yanıtındaki fiyatın ne zaman güncellendiğini nereden anlarım?
Yanıttaki lastUpdate alanı verinin en son ne zaman yazıldığını gösterir; dataAgeMs ise verinin kaç milisaniye önce tazelendiğini doğrudan verir. Bu değerleri kendi zaman diliminize çevirerek verinin tazeliğini kontrol edebilirsiniz.
Zaman damgası hangi zaman diliminde geliyor?
lastUpdate alanı UTC zamanı olarak ISO 8601 biçiminde gelir (sonundaki Z, UTC'yi belirtir). Uygulamanızda bunu Türkiye saatine (UTC+3) çevirerek kullanıcıya yerel saatle gösterirsiniz.
Fiyat verisi ne kadar güncel, gecikme ne kadar?
Hasfiyat REST, WebSocket ve Webhook üzerinden düşük gecikmeyle güncel fiyat sunar. WebSocket akışında güncellemeler anlık push edilir, böylece veriniz sürekli tazedir. Yanıttaki zaman damgasıyla verinin anlık tazeliğini doğrulayabilirsiniz.
Zaman damgasını Unix formatından okunur tarihe nasıl çeviririm?
Unix zaman damgasını dilinizin tarih fonksiyonlarıyla (JavaScript'te new Date, Python'da datetime) okunur tarihe çevirirsiniz. Ardından yerel zaman dilimine göre biçimlendirip kullanıcıya gösterirsiniz. Bu dönüşüm fiyatın kaç saniye önce güncellendiğini hesaplamak için de kullanışlıdır.
Piyasa kapalıyken zaman damgası ne gösterir?
Piyasa hareketsizken zaman damgası son geçerli güncellemenin zamanını yansıtır ve fiyat değişmeden aynı kalabilir. Bu durumda damganın eskimesi verinin bozuk olduğu anlamına gelmez, sadece yeni işlem olmadığını gösterir. Serbest piyasa alış-satış değerleri hareket başladığında yeniden güncellenir.
Altın fiyatı uç noktasının örnek JSON yanıtı nasıl görünür?
Yanıt; source, count, data, dataAgeMs, stale ve lastUpdate alanlarından oluşur. data listesinde her sembol için ayrı bir nesne bulunur: `{ "title": "HAS ALTIN", "buy": "6.421,99", "sell": "6.452,21" }`. Değerler Türkçe biçimli metindir; bu yapıyı kendi modelinize eşleyerek verileri okursunuz.
JSON yanıtında alış ve satış neden ayrı geliyor?
Sarrafiye ve döviz piyasasında alış (buy) ile satış (sell) fiyatları farklı olduğundan API bunları ayrı alanlar olarak döndürür. Uygulamanızda kullanıcıya hangi yönü göstereceğinize göre doğru alanı seçersiniz. Bu ayrım gram altından çeyreğe, USD'den EUR'ya tüm sembollerde geçerlidir.
Çoklu sembol isteğinde JSON nasıl yapılanır?
Çoklu sembol yanıtında data alanı, her sembolün ayrı bir nesne olduğu bir dizidir. Her öğede title, buy ve sell alanları bulunur; zaman bilgisi kalem bazında değil yanıtın lastUpdate alanındadır. Diziyi döngüyle dolaşarak ihtiyacınız olan sembolleri işlersiniz.
Ayar bazlı altın (995, 916, 750, 585) verisi JSON'da nasıl gelir?
Ayar bazlı ürünler kaynağın kendi başlıklarıyla ayrı nesneler olarak yer alır; örneğin harem kaynağında 22 AYAR ve 14 AYAR kalemleri bulunur. Her kalem için alış ve satış değerleri ayrı gelir. Kaynakta olmayan bir ayar için has altın fiyatını milyem oranıyla çarparak hesaplarsınız.
JSON yanıtında ons XAU, gümüş ve platin gibi kıymetli madenler de var mı?
Evet, 67'den fazla sembol arasında ons XAU'nun yanı sıra gümüş, platin ve paladyum gibi kıymetli madenler de bulunur. Her biri kendi sembol adıyla ayrı nesne olarak alış-satış değerleriyle döner. Kripto ve BIST hisseleri ise kapsam dışıdır.
Canlı altın & döviz verisine hemen bağlanın
Dakikalar içinde REST veya WebSocket ile gerçek zamanlı fiyat akışına başlayın.