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. 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; her zaman header tercih edin.
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 iki temel kodla karşılaşırsınız. `401 Unauthorized`, anahtarın eksik, hatalı veya süresi dolmuş olduğunu; `403 Forbidden` ise anahtarın geçerli ama istenen kaynağa (ör. planınıza dahil olmayan bir sembole) yetkisinin olmadığını gösterir. 401 için anahtarı ve header formatını kontrol edin, 403 için ise plan kapsamınızı gözden geçirin.
`429 Too Many Requests`, saniye ya da dakika bazlı istek kotanızı aştığınız anlamına gelir. Sağlıklı bir istemci bu durumda yanıttaki `Retry-After` başlığına ya da yanıt gövdesindeki bekleme süresine uyar ve üstel geri çekilme (exponential backoff) ile yeniden dener. Sunucu kaynaklı `500` ve `503` 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": { "code": 429, "message": "Rate limit exceeded", "retryAfter": 12 } }`. Uygulamanızın hata işleyicisini bu ortak şemaya göre yazmak, farklı hata türlerini tek bir kod yolunda temiz biçimde ele almanızı sağlar.
Rate Limit, Sayfalama ve Zaman Damgası
Rate limit yönetimini yalnızca 429'a tepki vererek değil, proaktif olarak da yapmalısınız. Çoğu API, her yanıtta `X-RateLimit-Limit`, `X-RateLimit-Remaining` ve `X-RateLimit-Reset` başlıklarını döndürür. Kalan kredinizi izleyip sıfıra yaklaşırken istek hızını kısmak, hiç 429 almamanın en sağlam yoludur. Anlık fiyat için sürekli sorgulamak yerine WebSocket (Socket.IO) aboneliği kullanmak, hem gecikmeyi hem de istek sayısını dramatik biçimde düşürür.
Geçmiş fiyat listeleri gibi büyük veri kümelerinde sayfalama devreye girer. Genellikle `page` ve `limit` parametreleri ya da imleç (cursor) tabanlı yaklaşım kullanılır; yanıt, `nextCursor` veya `hasMore` gibi alanlarla bir sonraki sayfanın var olup olmadığını bildirir. Tüm sayfaları tek seferde çekmek yerine ihtiyaç oldukça ilerlemek, hem bellek hem kota açısından verimlidir.
Fiyat verisinde zaman damgası kritik bir alandır. Yanıtlar tipik olarak UTC bazlı ISO 8601 (`2026-08-21T09:14:03.482Z`) ya da milisaniye epoch değeri taşır. İ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 gram altın yanıtı: `{ "symbol": "gram-altin", "bid": 5842.10, "ask": 5849.75, "ts": "2026-08-21T09:14:03.482Z" }`.
Hasfiyat API'si bu davranışların tamamını standart olarak sunar: Authorization header ile kimlik doğrulama, tutarlı hata JSON'ları, rate limit başlıkları, sayfalanmış geçmiş uçları ve milisaniye zaman damgaları. 67'den fazla sembolü REST, WebSocket ve Webhook üzerinden, 14 kaynak arasında failover ile aldığınız için, bu rehberdeki 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 da el sıkışma sırasında aynı anahtar 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 Socket.IO bağlantısında kimlik için 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.
403 hatası aldım, 401'den farkı nedir?
401 kimliğinizin doğrulanamadığını, yani anahtarın eksik veya geçersiz olduğunu gösterir. 403 ise kimliğiniz doğrulandığı halde o kaynağa erişim yetkinizin olmadığı anlamına gelir. 403 alıyorsanız paket/kapsam yetkinizi kontrol etmeniz gerekir.
429 Too Many Requests hatası ne anlama gelir?
429, belirli sürede izin verilenden fazla istek attığınızı, yani hız limitini aştığınızı gösterir. Bir süre bekleyip isteklerinizi yavaşlatarak yeniden denemelisiniz. Sık anlık veri gerekiyorsa tekrarlı REST sorgusu yerine WebSocket aboneliğine geçmek limit 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 kadar beklemeliyim?
Genel yaklaşım üstel geri çekilmedir: her başarısız denemede bekleme süresini kademeli artırırsınız. Yanıtta bekleme bilgisi varsa onu esas alın, yoksa birkaç saniyeyle başlayıp katlayarak devam edin. Anlık ihtiyaç yüksekse WebSocket'e geçmek tekrar 429 almanızı engeller.
Ç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 Socket.IO aboneliğiyle tüm sembolleri tek bağlantı üzerinden dinlersiniz. Böylece 429 riskini en aza indirirsiniz.
WebSocket kullanınca rate-limit tamamen kalkar mı?
WebSocket'te veri push edildiği için tekrarlı REST sorgularının yarattığı hız limiti baskısı büyük ölçüde ortadan kalkar. Tek bağlantı üzerinden sürekli güncel fiyat aldığınızdan çağrı sayınız çok düşer. Yine de bağlantı ve abonelik kurallarına uygun davranmanız beklenir.
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, 403 ve 500 hataları arasındaki fark nedir?
401 kimlik doğrulanamadı (anahtar eksik/geçersiz), 403 kimlik geçerli ama yetki yok, 500 ise sunucu tarafında hata anlamına gelir. 401 ve 403 istek tarafında çözülür; anahtar ve yetkinizi kontrol edin. 500'de ise bir süre bekleyip yeniden deneyin.
Hangi durumda 400 Bad Request alırım?
400 genelde isteğin biçiminin hatalı olmasından, örneğin geçersiz sembol adı ya da bozuk parametrelerden kaynaklanır. İstek URL'nizi ve gönderdiğiniz alanları dokümandaki beklenen formata göre kontrol edin. Doğru sembol ve parametrelerle istek başarıyla işlenir.
API hatalarını uygulamamda nasıl sağlıklı yönetirim?
Yanıtın durum kodunu her zaman kontrol edip 401/403 için yetki, 429 için geri çekilme, 500 için 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 14 veri kaynağı 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 nasıl çalışır?
Geniş sonuç listelerinde sayfalama parametreleriyle veriyi parçalar halinde çekip her sayfada belirli sayıda kayıt alırsınız. Bir sonraki sayfayı istemek için ilgili sayfa/limit parametrelerini artırırsınız. Bu yaklaşım büyük yanıtları tek seferde çekmenin getirdiği yükü azaltır.
Sayfalamada tüm sonuçları çektiğimi nasıl anlarım?
Genelde yanıt döndürülen kayıt sayısı istediğiniz limitten az olduğunda son sayfaya ulaştığınızı anlarsınız. Toplam kayıt sayısı bilgisini de kullanarak döngünüzü sonlandırırsınız. Böylece gereksiz boş sayfa isteklerinden kaçınırsınız.
Sadece ihtiyacım olan sembolleri çekersem sayfalamaya gerek kalır mı?
İhtiyacınız sınırlı sayıda sembolse çoklu sembol uç noktasına yalnızca o sembolleri iletmek genelde tek sayfada yeterli olur. Sayfalama esas olarak tüm katalog gibi geniş listeler çekilirken önem kazanır. Hedefli sorgu hem yanıtı küçültür hem hızlandırır.
Sayfalı istekte rate-limit'e takılır mıyım?
Çok sayıda sayfayı çok hızlı ardışık çekerseniz hız limitine takılıp 429 alabilirsiniz. Sayfa istekleri arasına kısa bekleme ekleyip sayfa boyutunu makul tutmak 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 zaman damgası alanı fiyatın en son ne zaman güncellendiğini gösterir. Bu değeri kendi zaman diliminize çevirerek verinin tazeliğini kontrol edebilirsiniz. Canlı akışta bu damga sürekli güncellenir.
Zaman damgası hangi zaman diliminde geliyor?
Zaman damgalarını tutarlı biçimde işlemek için genelde standart bir referans zaman kullanılır; uygulamanızda bunu Türkiye saatine (UTC+3) çevirebilirsiniz. Dönüşümü kendi tarafınızda yaparak kullanıcıya yerel saatle gösterirsiniz. Dokümandaki alan açıklamasını esas alın.
Fiyat verisi ne kadar güncel, gecikme ne kadar?
Hasfiyat REST, WebSocket ve Webhook üzerinden milisaniye/saniye altı 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 genelde her sembol için ayrı bir nesne içerir; sembol adı, alış ve satış değerleri ile bir zaman damgası alanı bulunur. Örneğin gram altın için buy ve sell alanları farklı değerler taşır. 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ı genelde her sembolün ayrı bir nesne olduğu bir dizi ya da sembol adıyla anahtarlanmış bir nesne biçiminde gelir. Her öğede alış, satış ve zaman damgası alanları bulunur. 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 kendi sembol adlarıyla (örneğin 995, 916, 750, 585 ayar) ayrı nesneler olarak yanıtta yer alır. Her ayar için alış ve satış değerleri ayrı gelir. İhtiyacınız olan ayarı sembol adına göre filtreleyerek okursunuz.
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ış ve zaman damgasıyla 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 Socket.IO ile gerçek zamanlı fiyat akışına başlayın.