API Dokümantasyonu

Başlangıç

API anahtarı alın. Panelde API Ayarları üzerinden bir kos_live_… anahtarı oluşturun.
Sunucunuzdan çağırın. Anahtarı yalnızca backend’de saklayın; tarayıcıya gömmeyin.
JSON yanıtı işleyin. Tüm endpoint’ler application/json döner.

Kimlik doğrulama

Tüm /api/v1/* isteklerinde API anahtarı zorunludur. İki yöntemden birini kullanın:

Authorization

Authorization: Bearer kos_live_xxxxxxxxxxxxxxxx

X-API-Key

X-API-Key: kos_live_xxxxxxxxxxxxxxxx

Anahtar sızdırılırsa panelden Yenile veya İptal et ile hemen geçersiz kılın.

Endpoints

Tüm yanıtlar application/json formatındadır. Başarılı cevaplarda ok: true döner.

Fiyatlar

Fiyat Yönetimi ve piyasa verisine ait endpoint’ler.

GET /api/v1/prices

Aktif ürün alış / satış değerleri ile merkezi piyasa verisini birlikte döner.

Örnek yanıt

{
  "ok": true,
  "data": {
    "organization_id": 1,
    "fetched_at": "2026-08-15T13:50:00+03:00",
    "is_stale": false,
    "status_message": "Piyasa verisi güncel.",
    "market": [
      { "code": "HAS_ALTIN", "name": "Has Altın", "buy": 3250.12, "sell": 3254.80 }
    ],
    "products": [
      { "id": 12, "name": "22 Ayar Bilezik", "buy": 2980.5, "sell": 3120.0 }
    ]
  },
  "meta": {
    "currency": "TRY",
    "timezone": "Europe/Istanbul",
    "docs": "https://kuyumos.com/api/docs"
  }
}

GET /api/v1/prices/products

Yalnızca tanımlı ürünlerin alış / satış değerlerini döner.

GET /api/v1/prices/market

Merkezi piyasa enstrümanlarını (altın, döviz vb.) döner. Ürün formülleri dahil değildir.

Hata kodları

HTTP	code	Anlam
401	`unauthorized`	Anahtar eksik, hatalı veya iptal edilmiş
429	`rate_limited`	Dakikalık istek limiti aşıldı

Hata gövdesi

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "Geçersiz veya pasif API anahtarı."
  }
}

Limitler

Oran limiti sabittir: 60 istek / dakika.
Yanıtlarda X-RateLimit-Limit ve X-RateLimit-Remaining başlıkları bulunur.
429 durumunda Retry-After saniyesini bekleyin.
Ürün değerleri, paneldeki formüllerinizle anlık hesaplanır.
Anahtarı panelden yenileyebilir veya iptal edebilirsiniz.

Örnekler

cURL

curl -s "https://kuyumos.com/api/v1/prices" \
  -H "Authorization: Bearer kos_live_YOUR_KEY" \
  -H "Accept: application/json"

PHP

$ch = curl_init('https://kuyumos.com/api/v1/prices');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer kos_live_YOUR_KEY',
        'Accept: application/json',
    ],
]);
$json = json_decode(curl_exec($ch), true);
curl_close($ch);

Node.js

const res = await fetch('https://kuyumos.com/api/v1/prices', {
  headers: {
    Authorization: 'Bearer kos_live_YOUR_KEY',
    Accept: 'application/json',
  },
});
const body = await res.json();