{ "openapi": "3.1.0", "info": { "title": "ItemGold Hunter External API", "version": "1.0.0", "description": "Hunter'ın doğrulanmış rakip/pazar verisine yetkili dış sistemlerin eriştiği SALT OKUNUR API.\n\n## Kimlik doğrulama\n`Authorization: Bearer hk_live_...` Token'ı Hunter hesabınızdaki **Hesabım** sayfasından üretirsiniz.\nSunucuda yalnız SHA-256 hash'i saklanır; kaybederseniz iptal edip yenisini üretmeniz gerekir.\n\n## Anahtarınızı tarayıcıya koymayın\nBu API yalnız **sunucudan sunucuya** kullanım için tasarlandı. Hiçbir yanıt CORS başlığı taşımaz, ancak CORS bir kimlik doğrulama mekanizması DEĞİLDİR: tarayıcı JavaScript'ine konan bir token herkes tarafından okunabilir ve curl ile kullanılabilir. Tarayıcıdan veri göstermeniz gerekiyorsa kendi backend'inizde bir proxy yazın.\n\n## Veri sözleşmesi\n* Para değerleri **integer minor birim** + `currency` olarak döner (`11428` + `TRY` = 114,28 TL). Formatlanmış string yoktur.\n* Komisyonlar **baz puan** (bps): `700` = %7.\n* **Bilinmeyen alanlar `null` kalır.** `0`, `TR` veya `epin` olarak tahmin edilmez.\n* **Bölge ve fulfillment sert kimliktir.** `GLOBAL`, `TR` ve bilinmeyen birbirine eşitlenmez; `epin`/`code` ile `topup`/`account` birleştirilmez.\n* Her gözlemde `observedAt` ve `freshness` bulunur. Fiyat **geçmişi** ile `latestObservedAt` farklı şeylerdir.\n* Ham HTML, dahili payload, token, e-posta veya kullanıcı bilgisi ASLA dönmez.\n\n## Sayfalama\nCursor tabanlıdır. `pagination.nextCursor` boş olana kadar aynı isteği tekrarlayın. `limit` tavanı **100**'dür.\nTanınmayan bir query parametresi sessizce yutulmaz, **400** döner.\n\n## Tazelik ve kota\nVeri tazeliği = toplama cadence'ı + kısa edge cache (fiyatlarda ≤30 sn). Bu API **gerçek zamanlıya yakındır**, gerçek zamanlı değildir.\n\nKotadan düşen maliyet birimi: `304` = 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.\n**ETag + `updatedSince` kullanan istemci neredeyse bedava çalışır.**\n\n## Sürüm politikası\n`v1` içinde yalnız **eklemeli** değişiklik yapılır (yeni alan, yeni uç, yeni opsiyonel parametre). Kırıcı değişiklik `/v2` olarak yayınlanır. Bir sürüm kapatılmadan en az 90 gün önce `Sunset` ve `Deprecation` başlıkları gönderilir.", "contact": { "name": "ItemGold Hunter" } }, "servers": [ { "url": "https://api.hunter.haltintas.com", "description": "Üretim" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "v1" } ], "paths": { "/v1/meta": { "get": { "summary": "Anahtarın kendi yetkilerini bildirir", "description": "", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Başarılı", "headers": { "ETag": { "schema": { "type": "string" }, "description": "If-None-Match ile gönderin; değişmemişse 304 döner ve kotadan düşmez." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-Hunter-Cache": { "schema": { "type": "string", "enum": [ "HIT", "MISS" ] } }, "Cache-Control": { "schema": { "type": "string" }, "description": "Her zaman no-store — istemci tarafında saklamayın." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "version": { "type": "string" }, "tokenId": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "allowedSources": { "type": [ "array", "null" ], "items": { "type": "string" } }, "fieldTier": { "type": "string", "enum": [ "basic", "extended" ] }, "limits": { "type": "object", "properties": { "ratePerMinute": { "type": "integer" }, "ratePerDay": { "type": "integer" }, "maxPageSize": { "type": "integer" } } } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "304": { "description": "Değişmedi (ETag eşleşti). Gövde yok, kotadan düşmez." }, "400": { "description": "Geçersiz istek", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Kimlik yok/geçersiz/iptal edilmiş", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope veya kaynak yetkisi yok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Kota aşıldı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sources": { "get": { "summary": "İzinli kaynakların listesi", "description": "Tedarikçi kaynakları (maliyet verisi taşıdıkları için) HİÇ listelenmez.", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Başarılı", "headers": { "ETag": { "schema": { "type": "string" }, "description": "If-None-Match ile gönderin; değişmemişse 304 döner ve kotadan düşmez." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-Hunter-Cache": { "schema": { "type": "string", "enum": [ "HIT", "MISS" ] } }, "Cache-Control": { "schema": { "type": "string" }, "description": "Her zaman no-store — istemci tarafında saklamayın." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "competitor", "itemgold" ] } } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "304": { "description": "Değişmedi (ETag eşleşti). Gövde yok, kotadan düşmez." }, "400": { "description": "Geçersiz istek", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Kimlik yok/geçersiz/iptal edilmiş", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope veya kaynak yetkisi yok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Kota aşıldı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "sources:read" } }, "/v1/products": { "get": { "summary": "Kanonik ürün listesi", "description": "", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Sayfa boyutu. Tavan 100 ZORUNLUDUR; aşılırsa 400." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Bir önceki yanıtın pagination.nextCursor değeri. Opak — ayrıştırmayın." }, { "name": "sources", "in": "query", "schema": { "type": "string" }, "description": "Virgüllü kaynak slug listesi. Anahtarın izinli olmadığı kaynak istenirse 403." }, { "name": "updatedSince", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Yalnız bu andan sonra değişenler. En fazla 90 gün geriye. YÜKSEK TRAFİKTE ÖNERİLEN yöntem — tam taramadan çok daha ucuz." }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 256 } }, { "name": "game", "in": "query", "schema": { "type": "string", "maxLength": 128 } }, { "name": "region", "in": "query", "schema": { "type": "string", "enum": [ "TR", "GLOBAL", "EU", "NA", "UK", "RU", "BR", "unknown" ] }, "description": "'unknown' bölgesi bilinmeyen kayıtları getirir. TR ile GLOBAL ASLA eşitlenmez." }, { "name": "fulfillmentType", "in": "query", "schema": { "type": "string", "enum": [ "epin", "code", "topup", "account", "unknown" ] } } ], "responses": { "200": { "description": "Başarılı", "headers": { "ETag": { "schema": { "type": "string" }, "description": "If-None-Match ile gönderin; değişmemişse 304 döner ve kotadan düşmez." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-Hunter-Cache": { "schema": { "type": "string", "enum": [ "HIT", "MISS" ] } }, "Cache-Control": { "schema": { "type": "string" }, "description": "Her zaman no-store — istemci tarafında saklamayın." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "304": { "description": "Değişmedi (ETag eşleşti). Gövde yok, kotadan düşmez." }, "400": { "description": "Geçersiz istek", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Kimlik yok/geçersiz/iptal edilmiş", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope veya kaynak yetkisi yok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Kota aşıldı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "products:read" } }, "/v1/products/{canonicalId}": { "get": { "summary": "Tek kanonik ürün", "description": "", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "canonicalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Başarılı", "headers": { "ETag": { "schema": { "type": "string" }, "description": "If-None-Match ile gönderin; değişmemişse 304 döner ve kotadan düşmez." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-Hunter-Cache": { "schema": { "type": "string", "enum": [ "HIT", "MISS" ] } }, "Cache-Control": { "schema": { "type": "string" }, "description": "Her zaman no-store — istemci tarafında saklamayın." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Product" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "304": { "description": "Değişmedi (ETag eşleşti). Gövde yok, kotadan düşmez." }, "400": { "description": "Geçersiz istek", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Kimlik yok/geçersiz/iptal edilmiş", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope veya kaynak yetkisi yok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Kota aşıldı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "products:read" } }, "/v1/products/{canonicalId}/prices": { "get": { "summary": "Kaynak başına GÜNCEL fiyat", "description": "", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "canonicalId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sources", "in": "query", "schema": { "type": "string" }, "description": "Virgüllü kaynak slug listesi. Anahtarın izinli olmadığı kaynak istenirse 403." } ], "responses": { "200": { "description": "Başarılı", "headers": { "ETag": { "schema": { "type": "string" }, "description": "If-None-Match ile gönderin; değişmemişse 304 döner ve kotadan düşmez." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-Hunter-Cache": { "schema": { "type": "string", "enum": [ "HIT", "MISS" ] } }, "Cache-Control": { "schema": { "type": "string" }, "description": "Her zaman no-store — istemci tarafında saklamayın." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "canonicalId": { "type": "string" }, "region": { "type": [ "string", "null" ] }, "fulfillmentType": { "type": [ "string", "null" ] }, "prices": { "type": "array", "items": { "$ref": "#/components/schemas/Price" } }, "summary": { "$ref": "#/components/schemas/PriceSummary" } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "304": { "description": "Değişmedi (ETag eşleşti). Gövde yok, kotadan düşmez." }, "400": { "description": "Geçersiz istek", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Kimlik yok/geçersiz/iptal edilmiş", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope veya kaynak yetkisi yok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Kota aşıldı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "prices:read" } }, "/v1/products/{canonicalId}/price-history": { "get": { "summary": "Fiyat geçmişi (zaman serisi)", "description": "AYRI scope ve daha yüksek kota maliyeti. Güncel fiyat için /prices kullanın.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "canonicalId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Sayfa boyutu. Tavan 100 ZORUNLUDUR; aşılırsa 400." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Bir önceki yanıtın pagination.nextCursor değeri. Opak — ayrıştırmayın." }, { "name": "sources", "in": "query", "schema": { "type": "string" }, "description": "Virgüllü kaynak slug listesi. Anahtarın izinli olmadığı kaynak istenirse 403." }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Başarılı", "headers": { "ETag": { "schema": { "type": "string" }, "description": "If-None-Match ile gönderin; değişmemişse 304 döner ve kotadan düşmez." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-Hunter-Cache": { "schema": { "type": "string", "enum": [ "HIT", "MISS" ] } }, "Cache-Control": { "schema": { "type": "string" }, "description": "Her zaman no-store — istemci tarafında saklamayın." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Price" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "304": { "description": "Değişmedi (ETag eşleşti). Gövde yok, kotadan düşmez." }, "400": { "description": "Geçersiz istek", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Kimlik yok/geçersiz/iptal edilmiş", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope veya kaynak yetkisi yok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Kota aşıldı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "prices:history" } }, "/v1/prices": { "get": { "summary": "Toplu güncel fiyat akışı", "description": "Senkron için updatedSince ile DELTA çekin; filtresiz tam tarama en pahalı işlemdir.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Sayfa boyutu. Tavan 100 ZORUNLUDUR; aşılırsa 400." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Bir önceki yanıtın pagination.nextCursor değeri. Opak — ayrıştırmayın." }, { "name": "sources", "in": "query", "schema": { "type": "string" }, "description": "Virgüllü kaynak slug listesi. Anahtarın izinli olmadığı kaynak istenirse 403." }, { "name": "updatedSince", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Yalnız bu andan sonra değişenler. En fazla 90 gün geriye. YÜKSEK TRAFİKTE ÖNERİLEN yöntem — tam taramadan çok daha ucuz." }, { "name": "region", "in": "query", "schema": { "type": "string" } }, { "name": "fulfillmentType", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Başarılı", "headers": { "ETag": { "schema": { "type": "string" }, "description": "If-None-Match ile gönderin; değişmemişse 304 döner ve kotadan düşmez." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-Hunter-Cache": { "schema": { "type": "string", "enum": [ "HIT", "MISS" ] } }, "Cache-Control": { "schema": { "type": "string" }, "description": "Her zaman no-store — istemci tarafında saklamayın." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Price" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "304": { "description": "Değişmedi (ETag eşleşti). Gövde yok, kotadan düşmez." }, "400": { "description": "Geçersiz istek", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Kimlik yok/geçersiz/iptal edilmiş", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope veya kaynak yetkisi yok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Kota aşıldı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "prices:read" } }, "/v1/categories": { "get": { "summary": "Kanonik kategori ağacı", "description": "", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Sayfa boyutu. Tavan 100 ZORUNLUDUR; aşılırsa 400." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Bir önceki yanıtın pagination.nextCursor değeri. Opak — ayrıştırmayın." }, { "name": "sources", "in": "query", "schema": { "type": "string" }, "description": "Virgüllü kaynak slug listesi. Anahtarın izinli olmadığı kaynak istenirse 403." } ], "responses": { "200": { "description": "Başarılı", "headers": { "ETag": { "schema": { "type": "string" }, "description": "If-None-Match ile gönderin; değişmemişse 304 döner ve kotadan düşmez." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-Hunter-Cache": { "schema": { "type": "string", "enum": [ "HIT", "MISS" ] } }, "Cache-Control": { "schema": { "type": "string" }, "description": "Her zaman no-store — istemci tarafında saklamayın." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "parentId": { "type": [ "string", "null" ] }, "level": { "type": "integer" }, "productCount": { "type": "integer" } } } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "304": { "description": "Değişmedi (ETag eşleşti). Gövde yok, kotadan düşmez." }, "400": { "description": "Geçersiz istek", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Kimlik yok/geçersiz/iptal edilmiş", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope veya kaynak yetkisi yok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Kota aşıldı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "categories:read" } }, "/v1/commissions": { "get": { "summary": "Kategori × satıcı tipi komisyonları", "description": "", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Sayfa boyutu. Tavan 100 ZORUNLUDUR; aşılırsa 400." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Bir önceki yanıtın pagination.nextCursor değeri. Opak — ayrıştırmayın." }, { "name": "sources", "in": "query", "schema": { "type": "string" }, "description": "Virgüllü kaynak slug listesi. Anahtarın izinli olmadığı kaynak istenirse 403." } ], "responses": { "200": { "description": "Başarılı", "headers": { "ETag": { "schema": { "type": "string" }, "description": "If-None-Match ile gönderin; değişmemişse 304 döner ve kotadan düşmez." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-Hunter-Cache": { "schema": { "type": "string", "enum": [ "HIT", "MISS" ] } }, "Cache-Control": { "schema": { "type": "string" }, "description": "Her zaman no-store — istemci tarafında saklamayın." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "competitor", "itemgold" ] } } }, "category": { "type": [ "object", "null" ] }, "sellerType": { "type": [ "string", "null" ] }, "commissionBps": { "type": [ "integer", "null" ], "description": "Baz puan: 700 = %7" }, "minPriceMinor": { "type": [ "integer", "null" ], "description": "" }, "maxPriceMinor": { "type": [ "integer", "null" ], "description": "" }, "fixedFeeMinor": { "type": [ "integer", "null" ], "description": "" }, "currency": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "observedAt": { "type": [ "string", "null" ] } } } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "304": { "description": "Değişmedi (ETag eşleşti). Gövde yok, kotadan düşmez." }, "400": { "description": "Geçersiz istek", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Kimlik yok/geçersiz/iptal edilmiş", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope veya kaynak yetkisi yok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Kota aşıldı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "commissions:read" } }, "/v1/payouts": { "get": { "summary": "Hakediş / ödeme kuralları", "description": "", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Sayfa boyutu. Tavan 100 ZORUNLUDUR; aşılırsa 400." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Bir önceki yanıtın pagination.nextCursor değeri. Opak — ayrıştırmayın." }, { "name": "sources", "in": "query", "schema": { "type": "string" }, "description": "Virgüllü kaynak slug listesi. Anahtarın izinli olmadığı kaynak istenirse 403." } ], "responses": { "200": { "description": "Başarılı", "headers": { "ETag": { "schema": { "type": "string" }, "description": "If-None-Match ile gönderin; değişmemişse 304 döner ve kotadan düşmez." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-Hunter-Cache": { "schema": { "type": "string", "enum": [ "HIT", "MISS" ] } }, "Cache-Control": { "schema": { "type": "string" }, "description": "Her zaman no-store — istemci tarafında saklamayın." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "competitor", "itemgold" ] } } }, "scope": { "type": [ "string", "null" ] }, "categoryName": { "type": [ "string", "null" ] }, "sellerType": { "type": [ "string", "null" ] }, "holdHours": { "type": [ "number", "null" ] }, "payoutTiming": { "type": [ "string", "null" ] }, "minPayoutMinor": { "type": [ "integer", "null" ], "description": "" }, "payoutFeeMinor": { "type": [ "integer", "null" ], "description": "" }, "fastOption": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "observedAt": { "type": [ "string", "null" ] } } } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "304": { "description": "Değişmedi (ETag eşleşti). Gövde yok, kotadan düşmez." }, "400": { "description": "Geçersiz istek", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Kimlik yok/geçersiz/iptal edilmiş", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope veya kaynak yetkisi yok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Kota aşıldı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "payouts:read" } }, "/v1/payment-methods": { "get": { "summary": "Ödeme yöntemleri ve komisyonları", "description": "", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Sayfa boyutu. Tavan 100 ZORUNLUDUR; aşılırsa 400." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Bir önceki yanıtın pagination.nextCursor değeri. Opak — ayrıştırmayın." }, { "name": "sources", "in": "query", "schema": { "type": "string" }, "description": "Virgüllü kaynak slug listesi. Anahtarın izinli olmadığı kaynak istenirse 403." }, { "name": "flow", "in": "query", "schema": { "type": "string", "enum": [ "deposit", "cashout" ] } } ], "responses": { "200": { "description": "Başarılı", "headers": { "ETag": { "schema": { "type": "string" }, "description": "If-None-Match ile gönderin; değişmemişse 304 döner ve kotadan düşmez." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-Hunter-Cache": { "schema": { "type": "string", "enum": [ "HIT", "MISS" ] } }, "Cache-Control": { "schema": { "type": "string" }, "description": "Her zaman no-store — istemci tarafında saklamayın." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "competitor", "itemgold" ] } } }, "name": { "type": "string" }, "providerType": { "type": [ "string", "null" ] }, "flows": { "type": "object", "properties": { "deposit": { "type": "boolean" }, "cashout": { "type": "boolean" } } }, "depositCommissionBps": { "type": [ "integer", "null" ] }, "cashoutCommissionBps": { "type": [ "integer", "null" ] }, "refundCommissionBps": { "type": [ "integer", "null" ] }, "depositFixedFeeMinor": { "type": [ "integer", "null" ], "description": "" }, "cashoutFixedFeeMinor": { "type": [ "integer", "null" ], "description": "" }, "minDepositMinor": { "type": [ "integer", "null" ], "description": "" }, "minCashoutMinor": { "type": [ "integer", "null" ], "description": "" }, "cashoutHoldHours": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "observedAt": { "type": [ "string", "null" ] } } } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "304": { "description": "Değişmedi (ETag eşleşti). Gövde yok, kotadan düşmez." }, "400": { "description": "Geçersiz istek", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Kimlik yok/geçersiz/iptal edilmiş", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope veya kaynak yetkisi yok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Kota aşıldı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "payments:read" } }, "/v1/complaints": { "get": { "summary": "Şikayet kayıtları", "description": "Üçüncü şahıs marka ve kullanıcı içeriği. Yeniden yayında kaynak gösterme ve yasal sorumluluk size aittir.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Sayfa boyutu. Tavan 100 ZORUNLUDUR; aşılırsa 400." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Bir önceki yanıtın pagination.nextCursor değeri. Opak — ayrıştırmayın." }, { "name": "sources", "in": "query", "schema": { "type": "string" }, "description": "Virgüllü kaynak slug listesi. Anahtarın izinli olmadığı kaynak istenirse 403." }, { "name": "updatedSince", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Yalnız bu andan sonra değişenler. En fazla 90 gün geriye. YÜKSEK TRAFİKTE ÖNERİLEN yöntem — tam taramadan çok daha ucuz." } ], "responses": { "200": { "description": "Başarılı", "headers": { "ETag": { "schema": { "type": "string" }, "description": "If-None-Match ile gönderin; değişmemişse 304 döner ve kotadan düşmez." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-Hunter-Cache": { "schema": { "type": "string", "enum": [ "HIT", "MISS" ] } }, "Cache-Control": { "schema": { "type": "string" }, "description": "Her zaman no-store — istemci tarafında saklamayın." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "source": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "competitor", "itemgold" ] } } }, "title": { "type": [ "string", "null" ] }, "excerpt": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "complaintDate": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } } } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "304": { "description": "Değişmedi (ETag eşleşti). Gövde yok, kotadan düşmez." }, "400": { "description": "Geçersiz istek", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Kimlik yok/geçersiz/iptal edilmiş", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope veya kaynak yetkisi yok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Kota aşıldı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "complaints:read" } }, "/v1/freshness": { "get": { "summary": "Kaynak × veri türü tazelik matrisi", "description": "", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Başarılı", "headers": { "ETag": { "schema": { "type": "string" }, "description": "If-None-Match ile gönderin; değişmemişse 304 döner ve kotadan düşmez." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-Hunter-Cache": { "schema": { "type": "string", "enum": [ "HIT", "MISS" ] } }, "Cache-Control": { "schema": { "type": "string" }, "description": "Her zaman no-store — istemci tarafında saklamayın." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "competitor", "itemgold" ] } } }, "datasets": { "type": "object" } } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "304": { "description": "Değişmedi (ETag eşleşti). Gövde yok, kotadan düşmez." }, "400": { "description": "Geçersiz istek", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Kimlik yok/geçersiz/iptal edilmiş", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope veya kaynak yetkisi yok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Kota aşıldı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "freshness:read" } }, "/v1/coverage": { "get": { "summary": "Kapsam istatistikleri", "description": "", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Başarılı", "headers": { "ETag": { "schema": { "type": "string" }, "description": "If-None-Match ile gönderin; değişmemişse 304 döner ve kotadan düşmez." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-Hunter-Cache": { "schema": { "type": "string", "enum": [ "HIT", "MISS" ] } }, "Cache-Control": { "schema": { "type": "string" }, "description": "Her zaman no-store — istemci tarafında saklamayın." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "totalProducts": { "type": "integer" }, "multiSourceProducts": { "type": "integer" }, "coveragePct": { "type": "number" }, "avgSourcesPerProduct": { "type": "number" } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "304": { "description": "Değişmedi (ETag eşleşti). Gövde yok, kotadan düşmez." }, "400": { "description": "Geçersiz istek", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Kimlik yok/geçersiz/iptal edilmiş", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope veya kaynak yetkisi yok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Kota aşıldı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "coverage:read" } } }, "components": { "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "invalid_request", "invalid_cursor", "unknown_parameter", "invalid_filter_value", "missing_credentials", "invalid_credentials", "revoked_credentials", "expired_credentials", "insufficient_scope", "source_not_permitted", "account_suspended", "not_found", "method_not_allowed", "rate_limited", "internal_error" ] }, "message": { "type": "string" }, "details": { "type": "object" }, "requestId": { "type": "string" } } } } }, "Meta": { "type": "object", "properties": { "version": { "type": "string", "const": "v1" }, "requestId": { "type": "string" }, "generatedAt": { "type": "string", "format": "date-time" } } }, "Pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] } } }, "Product": { "type": "object", "properties": { "canonicalId": { "type": "string" }, "name": { "type": "string" }, "game": { "type": [ "string", "null" ] }, "amount": { "type": [ "number", "null" ], "description": "Miktar (ör. 475). Bilinmiyorsa null — 0 olarak TAHMİN EDİLMEZ." }, "unit": { "type": [ "string", "null" ], "description": "VP, UC, TL gibi. Para birimi DEĞİLDİR." }, "region": { "type": [ "string", "null" ], "enum": [ "TR", "GLOBAL", "EU", "NA", "UK", "RU", "BR", null ], "description": "Sert kimlik. GLOBAL, TR ve null birbirine EŞİTLENMEZ. Bilinmiyorsa null." }, "fulfillmentType": { "type": [ "string", "null" ], "enum": [ "epin", "code", "topup", "account", null ], "description": "Sert kimlik. epin/code ile topup/account BİRLEŞTİRİLMEZ. Bilinmiyorsa null." }, "category": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "sourceCount": { "type": "integer" }, "latestObservedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "Price": { "type": "object", "properties": { "source": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "competitor", "itemgold" ] } } }, "priceMinor": { "type": [ "integer", "null" ], "description": "Liste fiyatı, integer MINOR birim (11428 = 114,28 TRY). Formatlanmış string dönmez." }, "originalPriceMinor": { "type": [ "integer", "null" ], "description": "İndirim öncesi fiyat." }, "discountPct": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ], "description": "ISO 4217. priceMinor bu birime aittir." }, "stockStatus": { "type": "string", "enum": [ "in_stock", "out_of_stock", "unknown" ], "description": "Ham stok adedi dışarı verilmez." }, "isFirstParty": { "type": "boolean" }, "sourceUrl": { "type": [ "string", "null" ], "description": "prices:sourceUrl scope'u ve extended alan tier'ı gerekir; aksi halde null." }, "reviewCount": { "type": [ "integer", "null" ] }, "rating": { "type": [ "number", "null" ] }, "observedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "BU gözlemin anı. latestObservedAt ile karıştırmayın." }, "freshness": { "type": "object", "properties": { "ageSeconds": { "type": [ "integer", "null" ] }, "isStale": { "type": "boolean" } } } } }, "PriceSummary": { "type": "object", "properties": { "lowestMinor": { "type": [ "integer", "null" ], "description": "" }, "highestMinor": { "type": [ "integer", "null" ], "description": "" }, "medianMinor": { "type": [ "integer", "null" ], "description": "" }, "currency": { "type": [ "string", "null" ] }, "sourceCount": { "type": "integer" } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Hesabınızın Hesabım sayfasından ürettiğiniz `hk_live_...` token'ı." } } } }