API Dokümantasyonu

Giriş

Hasfiyat API, kuyumcu ve döviz büroları için farklı kaynaklardan anlık altın ve döviz verilerini tek bir noktada toplar. REST API ve WebSocket Stream seçenekleri ile uygulamanıza en uygun veri akışını kolayca entegre edebilirsiniz.

API isteklerinizi doğrulamak için Authorization başlığında API anahtarınızı (Bearer Token) kullanmanız gerekir. Anahtarlarınızı panelde API Erişimi sayfasından oluşturabilirsiniz.

GET /api/prices HTTP/1.1
Host: api.hasfiyat.com
Authorization: Bearer YOUR_API_KEY

Aynı anahtarı x-api-key başlığıyla da gönderebilirsiniz. Başlık ekleyemediğiniz araçlarda ?apikey= sorgu parametresi de kabul edilir; adres sunucu kayıtlarında görünebileceği için mümkünse başlık kullanın. WebSocket bağlantısında başlık gönderilemediği için anahtar bağlantı adresindeki token parametresiyle iletilir.

Tüm bot verilerine tek bir uç nokta üzerinden erişebilirsiniz. Kaynak seçimi için `source` parametresini kullanın.

const url = "https://api.hasfiyat.com/api/prices?source=harem&symbols=GRAM,HAS";
const res = await fetch(url, { headers: { 'Authorization': 'Bearer YOUR_KEY' } });
console.log(await res.json());

// Birim bilgisi, ayarsiz (ham) deger ve turetilmis kalem
const url = "https://api.hasfiyat.com/api/prices?source=harem&symbols=GRAM ALTIN,ALTIN/GÜMÜŞ&birim=1&ham=1";
const res = await fetch(url, { headers: { 'Authorization': 'Bearer YOUR_KEY' } });
const j = await res.json();

console.log(j.lastUpdate);            // "2026-09-24T07:07:37.939Z" (mutlak an)
console.log(j.dataAgeMs, j.stale);   // 178  false  (goreli yas + bayatlik)
console.log(j.data[0]);              // { title, buy, sell, unit, currency }

const url = "https://api.hasfiyat.com/api/prices/" + encodeURIComponent("HAS ALTIN") + "?source=harem";
const res = await fetch(url, { headers: { Authorization: "Bearer YOUR_KEY" } });
console.log(await res.json());
// { source: "harem", data: { title: "HAS ALTIN", buy: "6.421,99", sell: "6.452,21" }, dataAgeMs, stale, lastUpdate }

WebSocket ile fiyatları sürekli sorgu atmadan, değiştikçe alırsınız. Bağlantı adresi tek satırdır; token REST'te kullandığınız API anahtarıdır, source değerleri aşağıdaki Kullanılabilir Kaynaklar listesindeki WS satırlarında yazar.

wss://api.hasfiyat.com/stream?source=harem&token=API_ANAHTARINIZ

• Bağlantı açılınca seçtiğiniz kaynağın tüm kalemlerini içeren bir JSON dizisi gelir; her elemanda title, buy ve sell alanları bulunur.
• Fiyat değiştikçe güncel dizi yeniden gönderilir, değişiklik yoksa mesaj gelmez. Her mesaj tam listedir; ihtiyacınız olan kalemleri istemci tarafında süzersiniz.
• Anahtar geçersizse, aktif paketiniz yoksa ya da source tanınmıyorsa sunucu {"error": "..."} mesajı gönderir ve bağlantıyı 1008 koduyla kapatır.
• Sunucu bağlantıyı canlı tutmak için 30 saniyede bir ping gönderir; tarayıcılar ve yaygın kütüphaneler buna kendiliğinden yanıt verir.
• Kopan bağlantı kendiliğinden yeniden kurulmaz; aşağıdaki örnekteki gibi artan beklemelerle yeniden bağlanın.
• WebSocket akışı aylık REST istek kotanızdan düşmez.

const url = "wss://api.hasfiyat.com/stream?source=harem&token=" + API_ANAHTARINIZ;
let bekleme = 1000;
let durdur = false;

function baglan() {
  const ws = new WebSocket(url);
  ws.onopen = () => { bekleme = 1000; };
  ws.onmessage = (e) => {
    const veri = JSON.parse(e.data);
    if (Array.isArray(veri)) {
      // [{ title: "HAS ALTIN", buy: "6.421,99", sell: "6.452,21" }, ...]
      console.log(veri.length + " kalem güncel");
    } else if (veri.error) {
      console.error("Sunucu:", veri.error); // ör. geçersiz anahtar
      durdur = true;                        // düzeltmeden yeniden deneme
    }
  };
  ws.onclose = () => {
    if (durdur) return;
    setTimeout(baglan, bekleme);
    bekleme = Math.min(bekleme * 2, 30000);
  };
}
baglan();

import asyncio, json, websockets

URL = "wss://api.hasfiyat.com/stream?source=harem&token=API_ANAHTARINIZ"

async def main():
    # Kopma olursa kütüphane artan beklemelerle yeniden bağlanır
    async for ws in websockets.connect(URL):
        try:
            async for mesaj in ws:
                veri = json.loads(mesaj)
                if isinstance(veri, list):
                    print(len(veri), "kalem güncel")
                else:
                    print("Sunucu:", veri.get("error"))
                    return  # ör. geçersiz anahtar: düzeltmeden yeniden deneme
        except websockets.ConnectionClosed:
            continue

asyncio.run(main())

Harem kaynağındaki kalemler için günlük (1d) ve saatlik (1h) OHLC geçmişi sunulur. Günlük veri 4 Ekim 2026'dan itibaren birikir, saatlik veri son 45 gün saklanır. Bu uca yapılan istekler aylık REST kotanızdan düşer.

const url = "https://api.hasfiyat.com/api/prices/history?symbol=" + encodeURIComponent("HAS ALTIN") + "&period=1d&from=2026-10-19&to=2026-10-25";
const res = await fetch(url, { headers: { Authorization: "Bearer YOUR_KEY" } });
const j = await res.json();

console.log(j.count, j.partialLastBar);  // bar sayısı, son bar henüz kapanmadıysa true
console.log(j.data[0]);
// { time: "2026-10-19", open: 6624.01, high: 6663.77, low: 6588.5, close: 6595.4,
//   buy: { open: 6601.95, high: 6642.04, low: 6557.59, close: 6561.44 },
//   timestamp: "2026-10-19T00:00:00+03:00", ts: 1792357200000 }

Aylık İstek Kotası

REST istekleri (liste, tek sembol ve tarihsel veri uçları) aylık kotayla sayılır. Kotanız paketinize göre belirlenir; güncel kullanımınızı ve kotanızı panelde görürsünüz. Kota dolduğunda istekler 429 ile yanıtlanır, yanıta X-Api-Quota: exceeded başlığı eklenir ve reddedilen istekler sayaca eklenmez. WebSocket akışı bu kotadan düşmez; fiyatları sık izliyorsanız REST'i döngüyle sorgulamak yerine WebSocket kullanın.

REST Hata Yanıtları

Hata gövdesinde insan okunur bir error mesajı ve kodunuzda kullanabileceğiniz makine okunur bir reason alanı bulunur. Kimlik doğrulama hatalarında isteğin geldiği IP de clientIp alanında döner.

{
  "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
}

Tanınmayan bir source değeri hata döndürmez; boş liste (count: 0) gelir. Kaynak adını Kullanılabilir Kaynaklar listesinden kontrol edin.

WebSocket Hata Mesajları

WebSocket tarafında hata, bağlantı kapanmadan hemen önce gönderilen {"error": "..."} mesajıyla bildirilir; bağlantı 1008 koduyla kapanır.

Webhook ile sürekli sorgu atmadan, fiyat değiştiğinde ya da belirlediğiniz eşik aşıldığında sunucunuza imzalı bir HTTPS bildirimi gelir. Webhook'ları panelde Webhook'lar sayfasından eklersiniz: adres, kaynak, kalemler ve olay türü. Starter paketinde 2, Pro'da 5, Enterprise'da 20 webhook tanımlanabilir. Bildirimler aylık REST kotanızdan düşmez.

• Değerler REST ile aynıdır: kaynağın kalemleri, panelde tanımladığınız Fiyat Ayarı uygulanmış hâliyle gelir; buy/sell Türkçe biçimli metindir (ör. "6.452,56").
• Yalnızca herkese açık https:// adresleri kabul edilir; yerel ve özel ağ adreslerine gönderim yapılmaz, yönlendirmeler (3xx) izlenmez.
• Aktif paketiniz sona ererse gönderim durur; paket yenilenince kendiliğinden devam eder.

Olay Türleri

Bildirim Gövdesi

Her bildirim POST ile application/json olarak gelir. price.update örneği:

{
  "id": "evt_3kQx9vB2mT7sLp4aZ1yW",
  "event": "price.update",
  "createdAt": "2026-10-26T09:15:02.418Z",
  "webhookId": "6650f0c2a1b2c3d4e5f60718",
  "source": "harem",
  "lastUpdate": "2026-10-26T09:15:01.902Z",
  "stale": false,
  "changed": ["HAS ALTIN"],
  "data": [
    { "title": "HAS ALTIN", "buy": "6.430,22", "sell": "6.452,56" },
    { "title": "USD/TL", "buy": "49,851", "sell": "49,915" }
  ]
}

price.threshold örneği (value, kuralın karşılaştırdığı sayısal değerdir):

{
  "id": "evt_Q2b7Lm0Xc4Vt9sNw1aRk",
  "event": "price.threshold",
  "createdAt": "2026-10-26T09:20:11.031Z",
  "webhookId": "6650f0c2a1b2c3d4e5f60719",
  "source": "harem",
  "lastUpdate": "2026-10-26T09:20:10.774Z",
  "stale": false,
  "rule": { "id": "6650f1d0a1b2c3d4e5f6071a", "symbol": "HAS ALTIN", "field": "sell", "op": "above", "value": 6450 },
  "value": 6452.56,
  "item": { "title": "HAS ALTIN", "buy": "6.430,22", "sell": "6.452,56" }
}

Başlıklar ve İmza

İmzayı ham gövde üzerinden doğrulayın (JSON'u ayrıştırıp yeniden yazmayın), karşılaştırmayı sabit zamanlı yapın ve zaman damgası 5 dakikadan eski istekleri reddedin. Gizli anahtar (whsec_…) oluşturulurken bir kez gösterilir; panelden yenileyebilirsiniz.

// Node.js (Express)
const crypto = require("crypto");

app.post("/hasfiyat-webhook", express.raw({ type: "application/json" }), (req, res) => {
  const zaman = req.get("X-Hasfiyat-Timestamp") || "";
  const beklenen = "sha256=" + crypto
    .createHmac("sha256", process.env.HASFIYAT_WEBHOOK_SECRET)
    .update(zaman + "." + req.body)
    .digest("hex");
  const gelen = req.get("X-Hasfiyat-Signature") || "";
  const gecerli = gelen.length === beklenen.length &&
    crypto.timingSafeEqual(Buffer.from(gelen), Buffer.from(beklenen));
  if (!gecerli || Math.abs(Date.now() / 1000 - Number(zaman)) > 300) return res.sendStatus(401);

  res.sendStatus(200);                 // önce hemen 200 dönün
  const olay = JSON.parse(req.body);   // sonra işleyin; olay.id ile tekrarları ayıklayın
});

<?php
$govde = file_get_contents('php://input');
$zaman = $_SERVER['HTTP_X_HASFIYAT_TIMESTAMP'] ?? '';
$beklenen = 'sha256=' . hash_hmac('sha256', $zaman . '.' . $govde, getenv('HASFIYAT_WEBHOOK_SECRET'));

if (!hash_equals($beklenen, $_SERVER['HTTP_X_HASFIYAT_SIGNATURE'] ?? '') || abs(time() - (int) $zaman) > 300) {
    http_response_code(401);
    exit;
}
http_response_code(200);
$olay = json_decode($govde, true);   // $olay['id'] ile tekrarları ayıklayın

import hashlib, hmac, os, time
from flask import Flask, abort, request

app = Flask(__name__)
GIZLI = os.environ["HASFIYAT_WEBHOOK_SECRET"].encode()

@app.post("/hasfiyat-webhook")
def hasfiyat_webhook():
    govde = request.get_data()
    zaman = request.headers.get("X-Hasfiyat-Timestamp", "")
    beklenen = "sha256=" + hmac.new(GIZLI, zaman.encode() + b"." + govde, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(beklenen, request.headers.get("X-Hasfiyat-Signature", "")):
        abort(401)
    if not zaman.isdigit() or abs(time.time() - int(zaman)) > 300:
        abort(401)
    olay = request.get_json()   # olay["id"] ile tekrarları ayıklayın
    return "", 200

Teslim ve Yeniden Deneme

• 8 saniye içinde 2xx yanıt dönün. 2xx dışındaki yanıtlar (yönlendirmeler dahil) ve zaman aşımı başarısız sayılır.
• Başarısız bildirim 15 saniye, 1 dakika ve 5 dakika sonra yeniden denenir (toplam 4 deneme). price.update için arada daha yeni değer oluştuysa eski bildirim yeniden denenmez, yenisi gönderilir.
• Aynı bildirim birden fazla gelebilir; id alanını (ya da X-Hasfiyat-Delivery başlığını) saklayıp tekrarları yok sayın.
• Adres 12 saat boyunca hiç başarılı yanıt vermezse webhook durdurulur; panelden yeniden etkinleştirirsiniz. Her webhook'un son teslimleri (durum kodu, süre, hata) panelde 7 gün görünür.
• İşi uzun süren uçlar, isteği hemen 200 ile kabul edip işi arka plana atmalıdır; yavaş uçlar yeniden denemeye ve tekrar gelen bildirimlere yol açar.

Kullanılabilir Kaynaklar

Her kaynak kendi sembol adlandırmasını kullanır. Aşağıdaki listeler 24.09.2026 tarihinde canlı uçtan okunarak üretilmiştir. Bir sembolü tam adıyla istemeniz en kesin sonucu verir; tam eşleşme tutmazsa sistem normalize eşleme ve takma ad çözümlemesini sırayla dener.

Birim ve Para Birimi

Değerler Türkçe biçimli metindir (binlik ., ondalık , — örn. 6.692,74). Ondalık basamak sayısı kaynağın hassasiyetini korur. Birim bilgisi sembol adına gömülüdür; alan olarak almak için birim=1 parametresini ekleyin.

Tanınmayan bir sembolde unit ve currency alanları null döner — yanlış birim bildirilmez.

buy / sell Ne Anlama Gelir?

buy alış, sell satış değeridir; piyasa yapıcısının perspektifinden verilir. buy piyasanın sizden aldığı, sell piyasanın size sattığı fiyattır. Her zaman buy < sell olur; aradaki fark makastır.

Türetilmiş Kalemler

Bazı semboller kaynakta bulunmaz; bunları adıyla istediğinizde API tarafında üretiriz. Kaynakta aynı adlı kalem varsa kaynak her zaman otoritedir, türetme yapılmaz. Hesap için gereken veri eksikse kalem hiç üretilmez — uydurma değer dönmez.

Kaynak Bazlı Sembol Listeleri

Başlığa tıklayarak o kaynağın tüm sembollerini açabilirsiniz. Parantez içindeki değer birimdir.

Yanıt Başlıkları

Gövdeyi ayrıştırmadan veri sağlığını izlemek için bu başlıkları kullanabilirsiniz.

Hasfiyat paneli; altın ürün fiyatlarınızı 16 pazaryeri ve e-ticaret mağazasına canlı altın kuruna göre otomatik aktarır. Fiyatlar gramaj, emtia kaynağı ve marj oranınıza göre hesaplanır; tampon ve volatilite eşikleriyle gereksiz güncellemeler engellenir.

Desteklenen Platformlar

Fiyat Nasıl Hesaplanır?

Her ürün için gramaj ve baz emtia (HAS, GRAM, 22 ayar, çeyrek vb.) tanımlanır. Fiyat, seçtiğiniz kaynağın canlı değerinden hesaplanır; tampon (buffer) ve volatilite eşiği ile küçük dalgalanmalarda gereksiz güncelleme yapılmaz, marjınız korunur.

Senkronizasyon Modları

Kurulum Adımları

1. 1Panelde Pazaryerleri sayfasına gidin ve yeni entegrasyon ekleyin.
2. 2Pazaryerini seçip kimlik bilgilerini (API anahtarı, mağaza adresi vb.) girin ve bağlantıyı doğrulayın.
3. 3Ürünleri çekin, gramaj ve baz emtiayı eşleştirin; alış/satış marjınızı belirleyin.
4. 4Test (Dry-run) modunda fiyatları önizleyin; doğruysa Canlı moda alıp gönderim sıklığını ayarlayın.