Altın Fiyat API Entegrasyon Rehberi: Ons, Gram ve Ziynet Fiyatlarını Hesaplama

İçindekiler

1. Altının tek bir fiyatı yoktur
2. Canlı ons altını çekmek
3. Ons → gram dönüşüm formülü
4. Çeyrek, yarım, tam ve bilezik
5. Önbellek, eşik ve kredi mimarisi
6. Gümüş, platin ve paladyum
7. Geçmiş seri ve getiri hesabı
8. En sık 5 entegrasyon hatası
9. Sık sorulan sorular

Altının Tek Bir Fiyatı Yoktur: Önce Bunu Modelleyin

Altın fiyatı entegrasyonlarında en sık görülen hata, tek bir sayıyı "altın fiyatı" diye veritabanına yazmaktır. Oysa aynı anda birbirinden farklı en az dört fiyat dolaşımdadır ve hepsinin kaynağı, birimi ve güncellenme sıklığı ayrıdır:

• Ons altın (XAU/USD): Küresel spot piyasada 1 troy ons (31,1034768 gram) saf altının dolar cinsinden fiyatı. Türkiye'deki bütün altın fiyatlarının kök referansıdır.
• Gram altın (TL): Ons fiyatının grama bölünüp güncel USD/TRY kuru ile çarpılmasıyla oluşan türev fiyat. Yani iki ayrı veri kaynağına — emtia ve döviz — aynı anda bağımlıdır.
• Ziynet altınları (çeyrek, yarım, tam, Cumhuriyet): Standart gramaj ve ayar üzerinden hesaplanır, üstüne darphane/işçilik payı biner. Bu yüzden matematiksel karşılığından her zaman bir miktar yüksektir.
• Kuyumcu alış–satış fiyatı: Yukarıdakilerin üstüne makas (spread) ve işçilik eklenmiş perakende fiyat. Bu bir piyasa verisi değil, işletme kararıdır; API'den beklenmemeli, sizin fiyatlama katmanınızda oluşturulmalıdır.

Sağlıklı bir mimari, API'den yalnızca ilk maddeyi otorite veri olarak alır, ikinci ve üçüncü maddeleri deterministik biçimde hesaplar, dördüncüsünü ise kendi iş kuralınıza bırakır. Aşağıdaki bölümler tam olarak bu üç katmanı kuruyor.

1. Adım: Canlı Ons Altını /commodities Ucundan Çekmek

apibir Emtia API'si değerli metalleri metals grubunda toplar. Altın için sembol XAU, gümüş için XAG'dır. Tek bir GET isteği yeterlidir:

curl --request GET \
  --url "https://api.apibir.com/v1/commodities?group=metals&symbol=XAU,XAG" \
  --header "authorization: apikey APIBIR-8f2c...9d41" \
  --header "accept: application/json"

const res = await fetch(
  "https://api.apibir.com/v1/commodities?symbol=XAU",
  { headers: { authorization: `apikey ${process.env.APIBIR_KEY}` } }
);
if (!res.ok) throw new Error(`apibir ${res.status}`);
const { data } = await res.json();
const altin = data.find((d) => d.symbol === "XAU");
console.log(altin.price, altin.unit); // 3418.62 'ons'

import os, requests

r = requests.get(
    "https://api.apibir.com/v1/commodities",
    params={"symbol": "XAU"},
    headers={"authorization": f"apikey {os.environ['APIBIR_KEY']}"},
    timeout=10,
)
r.raise_for_status()
altin = next(d for d in r.json()["data"] if d["symbol"] == "XAU")
print(altin["price"], altin["unit"])  # 3418.62 ons

<?php
$ch = curl_init("https://api.apibir.com/v1/commodities?symbol=XAU");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["authorization: apikey " . getenv("APIBIR_KEY")]);
$res = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $res["data"][0]["price"]; // ons/USD

Yanıtın ilgili kısmı şu şekilde döner:

{
  "success": true,
  "creditsUsed": 1,
  "creditsRemaining": 4821,
  "timestamp": "2026-08-20T10:42:05+03:00",
  "currency": "USD",
  "data": [
    {
      "symbol": "XAU",
      "name": "Altın (Ons)",
      "group": "metals",
      "unit": "ons",
      "price": 3418.62,
      "previousClose": 3392.10,
      "change": 26.52,
      "changePercent": 0.78,
      "dayLow": 3388.45,
      "dayHigh": 3424.90,
      "yearLow": 2611.30,
      "yearHigh": 3486.75,
      "updatedAt": "2026-08-20T10:41:58+03:00"
    }
  ]
}

Buradaki price alanı ons başına USD değeridir; unit alanı bunu açıkça söyler. unit alanını okumadan fiyatı grama çevirmeye kalkmak, ileride servis birim değiştirdiğinde sessizce yanlış fiyat üreten bir hataya dönüşür — her zaman kontrol edin.

Kısayol: unit=gram ve currency=TRY

Dönüşümü kendiniz yapmak istemiyorsanız API bunu sizin için yapabilir. currency parametresi fiyatı istediğiniz para birimine çevirir, unit=gram ise ons yerine gram bazına indirger:

curl --request GET \
  --url "https://api.apibir.com/v1/commodities?symbol=XAU&unit=gram&currency=TRY" \
  --header "authorization: apikey APIBIR-8f2c...9d41"

const url = new URL("https://api.apibir.com/v1/commodities");
url.searchParams.set("symbol", "XAU");
url.searchParams.set("unit", "gram");     // ons yerine gram bazı
url.searchParams.set("currency", "TRY");  // TL cinsinden

const { data } = await (await fetch(url, {
  headers: { authorization: `apikey ${process.env.APIBIR_KEY}` }
})).json();

console.log(data[0].price, data[0].unit); // gram altın / TRY

Bu yöntemin avantajı, kur dönüşümünün apibir tarafında aynı zaman damgasıyla yapılması; yani ons fiyatı ile kurun birbirinden 40 saniye kopuk olma riskinin ortadan kalkmasıdır. Kendi kur kaynağınızı kullanmak istiyorsanız bir sonraki bölüme geçin.

2. Adım: Ons → Gram Dönüşümünün Doğru Formülü

Dönüşüm tek satırlık bir çarpma gibi görünür ama üç ayrıntıda hata yapılır: troy ons sabitinin yuvarlanması, kurun alış mı satış mı olduğunun belirsizliği ve milyem (saflık) çarpanının atlanması.

const TROY_ONS_GRAM = 31.1034768; // yuvarlamayın

/**
 * @param {number} onsUsd     XAU fiyatı (USD/ons)
 * @param {number} usdTry     USD/TRY kuru (alış mı satış mı olduğuna siz karar verin)
 * @param {number} milyem     Saflık: 0.995 has, 0.916 = 22 ayar, 0.750 = 18 ayar
 */
function gramAltinTL(onsUsd, usdTry, milyem = 0.995) {
  return (onsUsd / TROY_ONS_GRAM) * usdTry * milyem;
}

// Örnek: 3418.62 USD/ons ve 41.20 USD/TRY
gramAltinTL(3418.62, 41.20);        // ≈ 4507.4 TL (has altın)
gramAltinTL(3418.62, 41.20, 0.916); // ≈ 4149.5 TL (22 ayar gram karşılığı)

from decimal import Decimal, ROUND_HALF_UP

TROY_ONS_GRAM = Decimal("31.1034768")

def gram_altin_tl(ons_usd, usd_try, milyem=Decimal("0.995")):
    """Para hesabında float yerine Decimal kullanın."""
    deger = (Decimal(str(ons_usd)) / TROY_ONS_GRAM) * Decimal(str(usd_try)) * milyem
    return deger.quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)

print(gram_altin_tl(3418.62, 41.20))                    # 4507.44
print(gram_altin_tl(3418.62, 41.20, Decimal("0.916")))  # 4148.85

Sabiti 31.1 diye kısaltmayın: 5.000.000 TL'lik bir külçe hesabında bu yuvarlama tek başına yaklaşık 5.500 TL sapma üretir. Kur tarafında ise ekranınızın amacına göre seçim yapın — müşteriye satış fiyatı gösteriyorsanız selling, portföy değerlemesi yapıyorsanız gösterge kuru mantıklıdır. apibir Döviz Kurları API'si her ikisini de ayrı alanlarda verir; nasıl çekileceğini TCMB ve serbest piyasa kurları rehberinde ayrıntılı anlattık.

3. Adım: Çeyrek, Yarım, Tam ve Bilezik Fiyatını Türetmek

Ziynet altınları standart gramaj ve ayarlara sahiptir. Saf altın karşılığı, gramajın milyem değeriyle çarpımıdır:

Formül her ürün için aynıdır: saf gram × gram altın TL fiyatı × (1 + işçilik oranı). İşçilik payı piyasa koşullarına ve ürüne göre değişir; bunu koda gömmek yerine yapılandırma dosyasından okumak, zam dönemlerinde deploy almadan güncelleyebilmenizi sağlar.

const ZIYNET = {
  ceyrek:      { gram: 1.750,  milyem: 0.916 },
  yarim:       { gram: 3.500,  milyem: 0.916 },
  tam:         { gram: 7.000,  milyem: 0.916 },
  cumhuriyet:  { gram: 7.216,  milyem: 0.916 },
  ata:         { gram: 7.216,  milyem: 0.916 },
};

function ziynetFiyat(tur, gramAltinTL, iscilikOrani = 0.04) {
  const u = ZIYNET[tur];
  if (!u) throw new Error(`Bilinmeyen ziynet türü: ${tur}`);
  const safGram = u.gram * u.milyem;          // saf altın karşılığı
  return safGram * gramAltinTL * (1 + iscilikOrani);
}

// gram altın 4507.44 TL iken
ziynetFiyat("ceyrek", 4507.44);  // ≈ 7517 TL
ziynetFiyat("tam", 4507.44);     // ≈ 30 068 TL

ZIYNET = {
    "ceyrek":     (1.750, 0.916),
    "yarim":      (3.500, 0.916),
    "tam":        (7.000, 0.916),
    "cumhuriyet": (7.216, 0.916),
}

def ziynet_fiyat(tur, gram_altin_tl, iscilik=0.04):
    gram, milyem = ZIYNET[tur]
    return round(gram * milyem * float(gram_altin_tl) * (1 + iscilik), 2)

print(ziynet_fiyat("ceyrek", 4507.44))

22 ayar bilezikte milyem 0,916 yerine bazı üreticilerde 0,900 olabilir; ürün kartınızda ayarı saklıyorsanız çarpanı oradan okuyun, sabitlemeyin.

4. Adım: Vitrin Ekranı Mimarisi — Önbellek, Eşik ve Kredi

Emtia servisi 60 saniyede bir güncellenir. Buna rağmen pek çok ekip ekranı her 2 saniyede bir yeniler ve ayın onuncu gününde kotasını bitirir. Doğru kurgu üç katmandan oluşur:

• 1

  Sunucu tarafında tek kaynak

  API'yi yalnızca sunucunuz çağırsın. 100 kullanıcının tarayıcısı doğrudan apibir'e gitmesin; hepsi sizin /api/altin ucunuzu okusun. Böylece 100 istek yerine 1 kredi harcarsınız ve anahtarınız istemci koduna sızmaz.

• 2

  Güncelleme periyoduna eşit TTL

  Önbellek süresini verinin tazelik süresine eşitleyin: 60 saniye. Daha kısası kredi yakar, daha uzunu kullanıcıya bayat fiyat gösterir.

• 3

  Fark eşiği ile yayın

  Her tazelemede ekranı baştan çizmek yerine yalnızca anlamlı değişimde (örneğin ±%0,05) istemciye push edin. Vitrin ekranlarında gereksiz titremeyi de önler.

Bu kurguyla 60 saniyelik TTL üzerinden ayda yaklaşık 43.200 istek yapılır. Ücretsiz plandaki 100 kredi/ay yalnızca geliştirme ve deneme içindir; sürekli çalışan bir vitrin ekranı için fiyatlandırma sayfasındaki kredi paketlerine bakmanız gerekir. TTL'i 5 dakikaya çıkarmak aynı ekranı ayda ~8.640 isteğe indirir; kuyumcu vitrini için 60 saniye, portföy raporu için 15 dakika genelde yeterlidir.

Aynı Sorguda Gümüş, Platin ve Paladyum

Kuyumcu ve yatırım uygulamalarının çoğu altınla başlar, birkaç hafta içinde gümüş talebiyle karşılaşır. Emtia servisinde değerli metallerin tamamı aynı metals grubunda olduğu için ikinci bir entegrasyona gerek yoktur: group=metals parametresi grubun tamamını tek kredi karşılığında döner. Semboller şu şekildedir:

Sembolleri koda tek tek yazmak yerine /commodities/groups ucundan sembol sözlüğünü çekip önbelleğe almak daha dayanıklı bir yaklaşımdır; servise yeni bir metal eklendiğinde uygulamanız kod değişikliği olmadan onu da listeler. Bu sözlük nadiren değiştiği için günde bir kez tazelemek yeterlidir.

Gümüşte dikkat edilecek nokta, gram fiyatının altına kıyasla çok küçük olması ve yuvarlama hatalarının oransal olarak daha görünür hale gelmesidir. Gümüş fiyatlarını kuruş yerine en az iki, tercihen üç ondalık basamakla saklayın; ekranda gösterirken yuvarlayın ama veritabanında ham hassasiyeti koruyun.

Geçmiş Seri: Grafik ve Getiri Hesabı

Ekranın altına "son 30 gün" grafiği koyacaksanız her gün için ayrı istek atmayın; /commodities/history tek sorguda günlük kapanış serisini döner:

curl --request GET \
  --url "https://api.apibir.com/v1/commodities/history?symbol=XAU&currency=TRY&range=30d" \
  --header "authorization: apikey APIBIR-8f2c...9d41"

import os, requests

r = requests.get(
    "https://api.apibir.com/v1/commodities/history",
    params={"symbol": "XAU", "currency": "TRY", "range": "30d"},
    headers={"authorization": f"apikey {os.environ['APIBIR_KEY']}"},
    timeout=15,
)
seri = r.json()["data"]           # [{"date": "...", "close": ...}, ...]

ilk, son = seri[0]["close"], seri[-1]["close"]
print(f"30 günlük getiri: %{(son - ilk) / ilk * 100:.2f}")

Getiri hesaplarken serideki kapanışların hangi para biriminde olduğuna dikkat edin. USD serisi üzerinden hesaplanan getiri "altının dünya piyasasındaki performansını", TRY serisi üzerinden hesaplanan getiri ise "altın + kur" bileşik performansını gösterir. İkisini aynı grafikte karşılaştırmak, içerik siteleri için değerli bir görselleştirmedir.

Sahada En Sık Görülen 5 Entegrasyon Hatası

Hata Yönetimi ve Geri Çekilme Stratejisi

Fiyat gösteren bir ekranda en kötü senaryo, hata anında ekranın boş kalması değil; eski fiyatın taze gibi gösterilmesidir. Kural basit: her fiyatın yanında updatedAt değerini taşıyın ve veri belirli bir yaşı geçtiğinde görsel olarak işaretleyin.

const MAX_YAS_MS = 5 * 60_000; // 5 dakikadan eski veriyi taze sayma

function fiyatDurumu(veri) {
  const yas = Date.now() - new Date(veri.updatedAt).getTime();
  if (yas > MAX_YAS_MS) {
    return { ...veri, bayat: true, uyari: "Fiyat gecikmeli olabilir" };
  }
  return { ...veri, bayat: false };
}

import time, requests

def istek_at(url, params, headers, deneme=4):
    for i in range(deneme):
        resp = requests.get(url, params=params, headers=headers, timeout=10)
        if resp.status_code == 429 or resp.status_code >= 500:
            time.sleep(2 ** i)          # 1s, 2s, 4s, 8s
            continue
        if resp.status_code == 402:
            raise RuntimeError("Kredi bitti — tekrar denemek çözmez, kotayı yükseltin")
        resp.raise_for_status()
        return resp.json()
    raise RuntimeError("apibir servisine ulaşılamadı")

429 rate_limited aldığınızda hemen tekrar denemeyin; üstel geri çekilme (exponential backoff) uygulayın. 402 insufficient_credits ise tekrar denemeyle çözülmez — bu bir kota sorunudur, uyarı kanalınıza düşmelidir. Tüm hata kodlarının listesi dokümantasyon sayfasında yer alıyor.

Sık Sorulan Sorular

Gram altın fiyatını doğrudan veren bir uç var mı?

Evet. /commodities ucuna symbol=XAU&unit=gram&currency=TRY parametrelerini eklediğinizde fiyat gram başına TL olarak döner. Kur dönüşümü apibir tarafında ons fiyatıyla aynı zaman damgası üzerinden yapılır, böylece iki kaynağı kendiniz senkronlamak zorunda kalmazsınız.

Altın fiyatı ne sıklıkla güncelleniyor?

Emtia servisi 60 saniyede bir güncellenir ve ortalama yanıt süresi yaklaşık 85 ms'dir. Önbellek süresini de 60 saniyeye eşitlemek, hem gereksiz kredi harcamasını hem de bayat veri gösterimini önler.

Kuyumcu alış-satış fiyatlarını API veriyor mu?

Hayır. API size piyasa referansı olan ons ve gram fiyatını verir; alış-satış makası ve işçilik payı her işletmenin kendi ticari kararıdır. Doğru yaklaşım, referans fiyatı API'den alıp kendi marj kurallarınızı üzerine uygulamaktır.

Çeyrek altın fiyatını hesaplarken neden 1,75 değil 1,603 gram kullanılıyor?

Çeyrek altının brüt gramajı 1,75 gramdır ancak 22 ayardır, yani içindeki saf altın oranı 0,916'dır. Fiyat saf altın içeriği üzerinden oluştuğu için 1,75 × 0,916 ≈ 1,603 gram saf altın karşılığı esas alınır; kalan fark alaşım ve işçiliktir.

Geçmiş altın fiyatlarına erişebilir miyim?

Evet, /commodities/history ucu günlük kapanış serilerini döner. Aralığı range parametresiyle belirlersiniz ve tek sorguda tüm seriyi aldığınız için her gün ayrı istek atmaya gerek kalmaz.

Ücretsiz plan bir kuyumcu ekranı için yeterli mi?

Ücretsiz plandaki 100 kredi/ay geliştirme ve deneme için tasarlanmıştır. 60 saniyelik yenileme ile kesintisiz çalışan bir ekran ayda yaklaşık 43.200 istek üretir; bu durumda fiyatlandırma sayfasındaki ücretli kredi paketlerinden birine geçmeniz gerekir.