ItemGold Hunter API

Doğrulanmış rakip ve pazar verisi için salt okunur REST API.

v1 · https://api.hunter.haltintas.com

KimlikBearer token, hesap bazlı

ErişimYalnız sunucudan sunucuya

YöntemSadece GET — API salt okunur

1. Başlarken

Token'ınızı Hunter hesabınızdaki Hesabım sayfasından üretirsiniz. Token yalnız bir kez gösterilir; sunucuda sadece SHA-256 hash'i saklanır. Kaybederseniz kurtarılamaz — iptal edip yenisini üretirsiniz.

curl -H "Authorization: Bearer $HUNTER_API_TOKEN" \
     https://api.hunter.haltintas.com/v1/meta

/v1/meta anahtarınızın yetkilerini, izinli kaynaklarını ve kota limitlerini döner.

Token'ınızı tarayıcıya koymayın.

Bu API yalnız sunucudan sunucuya kullanım içindir. Hiçbir yanıt CORS başlığı taşımaz — ama CORS bir kimlik doğrulama mekanizması değildir. Tarayıcı JavaScript'ine konan bir token DevTools'tan okunabilir ve curl ile kullanılabilir. Tarayıcıda veri göstermeniz gerekiyorsa kendi sunucunuzda bu API'yi çağıran ince bir proxy yazın.

2. Uçlar

Uç	Gereken yetki	Ne döner
`/v1/meta`	—	Anahtarınızın yetkileri ve kotası
`/v1/sources`	`sources:read`	Erişebildiğiniz kaynaklar
`/v1/products`	`products:read`	Kanonik ürün listesi
`/v1/products/{id}`	`products:read`	Tek ürün
`/v1/products/{id}/prices`	`prices:read`	Kaynak başına güncel fiyat + özet
`/v1/products/{id}/price-history`	`prices:history`	Fiyat zaman serisi
`/v1/prices`	`prices:read`	Toplu fiyat akışı (delta senkron için)
`/v1/categories`	`categories:read`	Kanonik kategori ağacı
`/v1/commissions`	`commissions:read`	Kategori × satıcı tipi komisyonları
`/v1/payouts`	`payouts:read`	Hakediş / ödeme kuralları
`/v1/payment-methods`	`payments:read`	Ödeme yöntemleri ve komisyonları
`/v1/complaints`	`complaints:read`	Şikayet kayıtları
`/v1/freshness`	`freshness:read`	Kaynak × veri türü tazelik matrisi
`/v1/coverage`	`coverage:read`	Kapsam istatistikleri

3. Veri sözleşmesi

Aşağıdakiler garantidir. İhlal edilirse bu bir hatadır, bize bildirin.

Para	Her zaman integer minor birim + `currency`. `11428` + `TRY` = 114,28 TL. Formatlanmış string asla dönmez.
Komisyon	Baz puan (bps). `700` = %7.
Bilinmeyen alanlar	`null` kalır. `0`, `TR` veya `epin` olarak tahmin edilmez.
Bölge	Sert kimliktir. `GLOBAL`, `TR` ve `null` birbirine eşitlenmez. `?region=unknown` bölgesi bilinmeyenleri getirir.
Fulfillment	Sert kimliktir. `epin`/`code` ile `topup`/`account` birleştirilmez.
Stok	Ham adet verilmez: `in_stock` / `out_of_stock` / `unknown`.
Tazelik	Her gözlemde `observedAt` ve `freshness` bulunur. Fiyat geçmişi ile ürünün `latestObservedAt` alanı farklı şeylerdir.

Sayfalama

Cursor tabanlıdır. limit tavanı 100'dür. nextCursor opaktır — ayrıştırmayın, olduğu gibi geri gönderin. Tanınmayan bir parametre sessizce yutulmaz, 400 döner.

GET /v1/products?limit=100
→ { "data": [...], "pagination": { "hasMore": true, "nextCursor": "eyJ2Ijox..." } }

GET /v1/products?limit=100&cursor=eyJ2Ijox...

Hatalar

{
  "error": {
    "code": "insufficient_scope",
    "message": "Bu token 'prices:history' yetkisine sahip değil.",
    "details": { "requiredScope": "prices:history" },
    "requestId": "req_01J..."
  }
}

Destek talebinde requestId değerini paylaşın.

4. Tazelik ve kota

Veri tazeliği = toplama cadence'ı + kısa edge önbelleği (fiyatlarda ≤30 sn). Bu API gerçek zamanlıya yakındır, gerçek zamanlı değildir. Her yanıt freshness taşır; kararlarınızı ona göre verin.

ETag + updatedSince kullanan istemci neredeyse bedava çalışır. Tam tarama döngüsüne giren istemci hızla limite çarpar.

ETag ile ucuz polling

GET /v1/freshness                    → 200, ETag: W/"a1b2c3..."
GET /v1/freshness
  If-None-Match: W/"a1b2c3..."       → 304, gövde yok, kotadan 0 birim

Delta senkron

GET /v1/prices?updatedSince=2026-07-27T13:00:00Z&limit=100

En fazla 90 gün geriye gidebilir. Düzenli senkronda tam tarama yerine bunu kullanın.

Kota maliyeti

İstek türü	Birim
`304 Not Modified`	0
Önbellek isabeti	1
Tekil kayıt	2
`updatedSince` ile delta liste	3
Normal liste	5
`price-history`	10
`updatedSince`'siz tam `/v1/prices` taraması	25

Her yanıt X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset taşır. 429 yanıtında Retry-After bulunur — ona uyun, sabit aralıkla yeniden denemeyin.

5. Sürüm politikası

v1 içinde yalnız eklemeli değişiklik yapılır: yeni alan, yeni uç, yeni opsiyonel parametre.
Var olan bir alanın adı, tipi veya anlamı değişmez; alan kaldırılmaz; zorunlu parametre eklenmez.
Kırıcı değişiklik /v2 olarak yayınlanır; iki sürüm bir süre paralel çalışır.
Bir sürüm kapatılmadan en az 90 gün önce Deprecation ve Sunset başlıkları gönderilir.

İstemcinizi buna göre yazın: tanımadığınız alanları yok sayın, alan sırasına güvenmeyin.

6. Yeniden yayın sorumluluğu

Şikayet kayıtları üçüncü şahıs marka ve kullanıcı içeriğidir; yeniden yayınının hukuki sorumluluğu size aittir.
Fiyat ve politika verisi toplama anındaki gözlemdir. "Şu an geçerli fiyat" olarak sunulması yanıltıcı olabilir — observedAt bilgisini birlikte gösterin.