{ "openapi": "3.0.3", "info": { "title": "Kopazar B2B API", "version": "2.3", "description": "Kopazar B2B API ile e-pin ve gold ürünlerini kendi sisteminizden satabilir, fiyat ve stok seviyelerini çekebilir, siparişlerinizi izleyebilirsiniz. REST + JSON; tüm istek gövdeleri `application/json`.\n\n### Hızlı başlangıç\n1. **Başvuru:** [API başvuru formu](https://www.kopazar.com/user-webapi-form) → onay sonrası kullanıcı adı, parola ve Client ID verilir.\n2. **Token:** `POST /token` → `access_token` (1 saat). Her istekte `Authorization: Bearer `.\n3. **Katalog & fiyat:** `/pricelist` (tek çağrı) veya `/categorylist` → `/epinlist` / `/goldlist`.\n4. **Stok:** `/stock-all` (periyodik senkron) veya `/stock` / `/stock-multi`. Stok yalnız **var/yok** olarak döner (0 yok · 1 var); adet asla verilmez.\n5. **Sipariş:** `/epinbuy` (kodlar yanıtta anında) · `/goldbuy` (operatör onayı, `pending`). `transid` ile idempotent.\n6. **Takip:** `/order-status` (kodları yeniden verir) veya webhook.\n\n### Scope'lar\n| Scope | Açtığı uçlar |\n|---|---|\n| `me` | /me, /limits, /ip-manage, /rotate-key, /usage-stats, /webhook-* |\n| `epin` | /epinbuy + katalog, stok, sipariş sorgu/iptal |\n| `gold` | /goldbuy + katalog, stok, sipariş sorgu/iptal |\n| `price` | yalnız /pricelist, /categorylist, /epinlist, /goldlist (fiyat-görüntüleme hesapları) |\n\n### Sandbox\nHesabınız sandbox modundaysa `/epinbuy` ve `/goldbuy` gerçek sipariş oluşturmaz, bakiye düşmez; `sandbox-e-1-XXXXXXXX` biçiminde sipariş no ve `TEST-XXXXX-XXXXX-XXXXX` kodlar döner. `/order-status` ve `/order-cancel` bu id'lerle çalışır. Sandbox modunu panelden açıp kapatırsınız.\n\n### Webhook (sipariş durumu bildirimi)\nPanelde tanımlı URL'inize `POST`, gövde JSON:\n```json\n{\"event\":\"order.status\",\"transid\":\"ORDER-2026-000124\",\"order_id\":2231764,\"order_type\":\"gold\",\"status\":\"success\",\"timestamp\":\"2026-10-02 22:45:10\"}\n```\nBaşlıklar: `X-Kopazar-Timestamp` (unix saniye) · `X-Kopazar-Signature` = `hex( HMAC-SHA256( timestamp + \".\" + rawBody , clientsalt ) )` · `X-Kopazar-Client` (client id).\nDoğrulama: imzayı aynı formülle üretip **sabit zamanlı** karşılaştırın; 5 dakikadan eski timestamp'i reddedin; `2xx` dönün. Başarısız teslimat 1-2-4-8-16 dk aralıkla yeniden denenir (yalnız `2xx` yanıt başarı sayılır). Webhook her API siparişi için gönderilir: anında teslim edilen e-pinlerde siparişten hemen sonra, gold ve sanal/top-up ürünlerde sipariş sonuçlanınca (`success` / `cancel`).\n\n### Görünürlük\nAPI yalnız sitede satışta olan ürünleri döner: aktif bir kategoride listelenen aktif e-pinler ve gold satışı açık kategorilerdeki aktif gold ürünleri. Sitede görünmeyen bir ürün listelerde yer almaz; `stock` ve satın alma uçları \"Urun satista degil\" döner.\n\n### Hata modeli ve limitler\nTüm yanıtlar `success` alanı taşır; hata durumunda `success:false` ve açıklayıcı `message`. Çoğu hata HTTP 200 ile döner — **daima `success` alanına bakın**, dallanma için `error_code` kullanın. Limitler: varsayılan 60 istek/dk, 1000/saat, 10 satın alma/dk (hesap bazlı değiştirilebilir); geçersiz uç denemeleri IP başına 10/dk ile sınırlıdır (429).\n\n\n### Hata kodları\nHer hata yanıtında `error_code` (sabit anahtar) bulunur; `message` insan için açıklamadır.\n\n| error_code | Anlamı |\n|---|---|\n| `AUTH_TOKEN_MISSING` / `AUTH_TOKEN_EXPIRED` / `AUTH_TOKEN_INVALID` | Token yok / süresi dolmuş / geçersiz → `/token` ile yenileyin |\n| `AUTH_TOKEN_REVOKED` | `/rotate-key` ya da şifre değişimi sonrası token iptal edildi → `/token` ile yeniden giriş yapın |\n| `ACCOUNT_DISABLED` | API hesabı veya üyelik pasif → destekle iletişime geçin |\n| `AUTH_CREDENTIALS` / `AUTH_LOCKED` | Kullanıcı adı-parola-clientid hatalı / çok deneme, geçici kilit |\n| `AUTH_IP_DENIED` / `AUTH_IP_REQUIRED` | IP beyaz listesinde değil / beyaz liste boş — panelden (API Ayarları > Güvenlik) sunucu IP'nizi girmeden istek yapılamaz |\n| `AUTH_SCOPE_DENIED` / `VALIDATION_SCOPE` | Token'ın scope'u bu uca yetmiyor / scope tanımsız |\n| `PRICE_ONLY_ACCOUNT` | Hesap yalnız fiyat görüntüleyebilir |\n| `RATE_LIMITED` | İstek limiti aşıldı (Retry-After) |\n| `INVALID_OPERATION` / `SERVICE_DISABLED` | Geçersiz uç / API geçici kapalı |\n| `VALIDATION` / `VALIDATION_DATE` | Eksik ya da hatalı parametre / tarih |\n| `PRODUCT_NOT_FOUND` / `PRODUCT_NOT_FOR_SALE` | Ürün yok / sitede satışta değil |\n| `OUT_OF_STOCK` / `QUANTITY_LIMIT` | Stok yetersiz / adet sınırı (min, max, günlük) |\n| `BALANCE_INSUFFICIENT` / `SALES_LIMIT_EXCEEDED` / `PURCHASE_BANNED` | Bakiye yetersiz / günlük-aylık satış limiti / hesapta alım yasağı |\n| `DUPLICATE_TRANSID` | Aynı transid ile sipariş zaten var (yanıtta `order_id`) |\n| `LOCKED_RETRY` | Aynı işlem şu an işleniyor, kısa süre sonra tekrar deneyin |\n| `ORDER_NOT_FOUND` / `ORDER_NOT_CANCELLABLE` | Sipariş yok / iptal edilemez |\n| `WEBHOOK_URL_MISSING` / `WEBHOOK_URL_BLOCKED` / `WEBHOOK_ERROR` | Webhook URL yok / özel IP / teslim hatası |\n| `METHOD_NOT_ALLOWED` / `UNSUPPORTED_CONTENT_TYPE` / `PAYLOAD_TOO_LARGE` | Geçit: yanlış HTTP metodu / Content-Type JSON değil / gövde 64 KB üstü |\n| `UPSTREAM_ERROR` | Geçit ana sunucuya ulaşamadı (502), tekrar deneyin |\n| `NOT_APPLICABLE` / `UPSTREAM_ERROR` | Bu ürün için işlem gerekmiyor / dış doğrulama servisine ulaşılamadı |\n| `INTERNAL_ERROR` / `ERROR` | Sunucu hatası / sınıflandırılmamış |\n\nDestek: destek@kopazar.com · Panel: [API ayarları](https://www.kopazar.com/user-webapi-setting)", "contact": { "name": "Kopazar Destek", "email": "destek@kopazar.com", "url": "https://www.kopazar.com" }, "x-logo": { "url": "./kopazar-logo.svg", "altText": "Kopazar" } }, "servers": [ { "url": "https://api.kopazar.com/webapi", "description": "Üretim (API geçidi)" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "1 · Kimlik", "description": "Token alma ve yenileme" }, { "name": "2 · Katalog & Fiyat", "description": "Kategoriler, ürünler, fiyat listesi" }, { "name": "3 · Stok", "description": "Stok var/yok (adet verilmez)" }, { "name": "4 · Sipariş", "description": "Satın alma, durum sorgu, iptal" }, { "name": "5 · Webhook", "description": "Bildirim testi ve kayıtları" }, { "name": "6 · Hesap", "description": "Bakiye ve limitler" }, { "name": "7 · Hesap Yönetimi", "description": "IP listesi, anahtar yenileme, istatistik" } ], "paths": { "/token": { "post": { "tags": [ "1 · Kimlik" ], "summary": "Erişim token'ı al", "description": "Bayi kimlik bilgileriyle 1 saat geçerli JWT erişim token'ı ve yenileme token'ı üretir. Her istekte `Authorization: Bearer ` başlığı gönderilir.\n\n**Scope:** virgülle ayrılmış: `gold`, `epin`, `me`, `price`. Yalnız ihtiyaç duyduğunuz scope'ları isteyin. `price` yalnız fiyat-görüntüleme hesapları içindir (sadece `/pricelist`).\n\n**Güvenlik:** 5 başarısız denemede kullanıcı/IP geçici kilitlenir. IP beyaz listesi **zorunludur**: panelde (API Ayarları > Güvenlik) en az bir sunucu IP'si tanımlı olmadan token alınamaz; yalnız o IP'lerden istek kabul edilir.", "operationId": "post_token", "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "access_token": { "type": "string", "description": "JWT erişim token'ı (1 saat)", "example": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9..." }, "refresh_token": { "type": "string", "description": "Yenileme token'ı", "example": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9..." }, "expires_in": { "type": "integer", "description": "Saniye", "example": 3600 }, "token_type": { "type": "string", "description": "", "example": "Bearer" } } }, "example": { "success": true, "access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...", "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...", "expires_in": 3600, "token_type": "Bearer" } } } }, "401": { "description": "Kimlik/yetki hatası (token yok, süresi dolmuş, scope yetersiz, IP izinsiz). HTTP gövdesi 200 dönebilir; `success:false` ve `message` alanına bakın.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "429": { "description": "İstek limiti aşıldı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string", "description": "API kullanıcı adı", "example": "bayi_kullanici" }, "password": { "type": "string", "description": "API parolası", "example": "••••••••" }, "clientid": { "type": "string", "description": "Client ID (panelden)", "example": "171542" }, "scope": { "type": "string", "description": "Virgülle ayrılmış scope listesi", "example": "me,epin,gold" } }, "required": [ "username", "password", "clientid", "scope" ] }, "example": { "username": "bayi_kullanici", "password": "••••••••", "clientid": "171542", "scope": "me,epin,gold" } } } }, "security": [] } }, "/refresh-token": { "post": { "tags": [ "1 · Kimlik" ], "summary": "Token yenile", "description": "Yenileme token'ı ile yeni bir erişim token'ı üretir. Scope değişmez. Yalnız POST gövdesinden kabul edilir; erişim token'ı yenileme için kullanılamaz. Hesap pasifse (`ACCOUNT_DISABLED`) ya da `/rotate-key` / şifre değişimiyle token iptal edildiyse (`AUTH_TOKEN_REVOKED`) `/token` ile yeniden giriş yapın.", "operationId": "post_refresh_token", "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "access_token": { "type": "string", "description": "", "example": "eyJ..." }, "expires_in": { "type": "integer", "description": "", "example": 3600 }, "token_type": { "type": "string", "description": "", "example": "Bearer" } } } } } }, "401": { "description": "Kimlik/yetki hatası (token yok, süresi dolmuş, scope yetersiz, IP izinsiz). HTTP gövdesi 200 dönebilir; `success:false` ve `message` alanına bakın.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "429": { "description": "İstek limiti aşıldı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "refresh_token": { "type": "string", "description": "", "example": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9..." } }, "required": [ "refresh_token" ] } } } }, "security": [] } }, "/categorylist": { "post": { "tags": [ "2 · Katalog & Fiyat" ], "summary": "Kategori listesi", "description": "Aktif ürün kategorilerini döner. **Scope:** `price`, `gold` veya `epin`.", "operationId": "post_categorylist", "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "list": { "type": "array", "description": "Kategoriler", "items": { "type": "object", "properties": { "category_id": { "type": "integer", "description": "", "example": 606 }, "name": { "type": "string", "description": "", "example": "Knight Online Premium" } } } } } } } } }, "401": { "description": "Kimlik/yetki hatası (token yok, süresi dolmuş, scope yetersiz, IP izinsiz). HTTP gövdesi 200 dönebilir; `success:false` ve `message` alanına bakın.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "429": { "description": "İstek limiti aşıldı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "producttype": { "type": "string", "enum": [ "epin", "gold" ], "description": "Boş bırakılırsa tümü", "example": "epin" } } } } } } } }, "/epinlist": { "post": { "tags": [ "2 · Katalog & Fiyat" ], "summary": "E-pin ürünleri", "description": "Aktif e-pin ürünlerini (id, ad, fiyat) döner. **Scope:** `price` veya `epin`.", "operationId": "post_epinlist", "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "list": { "type": "array", "description": "", "items": { "type": "object", "properties": { "product_epin_id": { "type": "integer", "description": "", "example": 3 }, "name": { "type": "string", "description": "", "example": "Bronze Premium" }, "price": { "type": "number", "description": "Size özel fiyat (TL)", "example": 125 }, "extra": { "type": "array", "description": "Top-up ürünlerinde istenen ek alanlar (yoksa alan dönmez)", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Siparişte `extra_` olarak gönderilir", "example": "joygameusername" }, "name": { "type": "string", "description": "", "example": "Joygame Kullanıcı Adınız" } } } }, "min_buy": { "type": "integer", "description": "Tek siparişte asgari adet", "example": 1 }, "max_buy": { "type": "integer", "description": "Tek siparişte azami adet (0 = sınırsız)", "example": 10 } } } } } } } } }, "401": { "description": "Kimlik/yetki hatası (token yok, süresi dolmuş, scope yetersiz, IP izinsiz). HTTP gövdesi 200 dönebilir; `success:false` ve `message` alanına bakın.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "429": { "description": "İstek limiti aşıldı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "category_id": { "type": "integer", "description": "Kategori filtresi (opsiyonel)", "example": 606 } } } } } } } }, "/goldlist": { "post": { "tags": [ "2 · Katalog & Fiyat" ], "summary": "Gold ürünleri", "description": "Aktif gold ürünlerini (id, kategori, ad, fiyat) döner. **Scope:** `price` veya `gold`.", "operationId": "post_goldlist", "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "list": { "type": "array", "description": "", "items": { "type": "object", "properties": { "product_gold_id": { "type": "integer", "description": "", "example": 13 }, "category_id": { "type": "integer", "description": "", "example": 694 }, "name": { "type": "string", "description": "", "example": "Dandanakan" }, "price": { "type": "number", "description": "Satış fiyatı (TL)", "example": 8 }, "min_buy": { "type": "integer", "description": "Tek siparişte asgari adet", "example": 1 }, "max_buy": { "type": "integer", "description": "Tek siparişte azami adet (0 = sınırsız)", "example": 10 } } } } } } } } }, "401": { "description": "Kimlik/yetki hatası (token yok, süresi dolmuş, scope yetersiz, IP izinsiz). HTTP gövdesi 200 dönebilir; `success:false` ve `message` alanına bakın.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "429": { "description": "İstek limiti aşıldı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "category_id": { "type": "integer", "description": "Kategori filtresi (opsiyonel)", "example": 694 } } } } } } } }, "/pricelist": { "post": { "tags": [ "2 · Katalog & Fiyat" ], "summary": "Fiyat listesi", "description": "Tüm aktif ürünlerin güncel fiyatını tek çağrıda döner. Fiyat-görüntüleme (`price` scope) hesaplarında yalnız size tanımlanan kategori/ürünler listelenir. Her ürün için `in_stock` (1 = stokta var, 0 = yok) döner; stok adedi dönmez. Gold satırlarında `buy_price`/`buy_active` (oyuncudan alış fiyatı, sitedeki 'Bize Sat' ile aynı) da yer alır. Fiyat-only hesaplar stok durumunu bu alandan alır (ayrı `/stock` çağrısı gerekmez). **Scope:** `price`, `gold` veya `epin`.", "operationId": "post_pricelist", "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "count": { "type": "integer", "description": "", "example": 2 }, "products": { "type": "array", "description": "", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "epin", "gold" ], "description": "" }, "product_id": { "type": "integer", "description": "", "example": 3 }, "name": { "type": "string", "description": "", "example": "Bronze Premium" }, "price": { "type": "number", "description": "E-pin: fiyat (TL)", "example": 125 }, "sell_price": { "type": "number", "description": "Gold: satış fiyatı (TL)" }, "buy_price": { "type": "number", "description": "Gold: oyuncudan alış fiyatımız (TL); yalnız gold satırlarında", "example": 7.20000000000000017763568394002504646778106689453125 }, "buy_active": { "type": "boolean", "description": "Gold: şu an alım yapılıyor mu (false ise buy_price gösterilmemeli)", "example": true }, "category_id": { "type": "integer", "description": "", "example": 606 }, "in_stock": { "type": "string", "enum": [ 0, 1 ], "description": "Stok durumu (1 var / 0 yok)", "example": 1 }, "min_buy": { "type": "integer", "description": "Tek siparişte asgari adet", "example": 1 }, "max_buy": { "type": "integer", "description": "Tek siparişte azami adet (0 = sınırsız)", "example": 10 } } } } } }, "example": { "success": true, "count": 2, "products": [ { "type": "epin", "product_id": 3, "name": "Bronze Premium", "price": 125, "category_id": 606, "in_stock": 1 }, { "type": "gold", "product_id": 13, "name": "Dandanakan", "sell_price": 8, "buy_price": 7.20000000000000017763568394002504646778106689453125, "buy_active": true, "category_id": 694, "in_stock": 1 } ] } } } }, "401": { "description": "Kimlik/yetki hatası (token yok, süresi dolmuş, scope yetersiz, IP izinsiz). HTTP gövdesi 200 dönebilir; `success:false` ve `message` alanına bakın.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "429": { "description": "İstek limiti aşıldı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "product_type": { "type": "string", "enum": [ "epin", "gold" ], "description": "Boş = tümü" }, "category_id": { "type": "integer", "description": "Kategori filtresi (opsiyonel)", "example": 606 } } } } } } } }, "/stock": { "post": { "tags": [ "3 · Stok" ], "summary": "Tek ürün stok", "description": "Bir ürünün stok durumunu, fiyatını ve sipariş sınırlarını döner. **Scope:** `gold` veya `epin`.", "operationId": "post_stock", "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "product_id": { "type": "integer", "description": "", "example": 262 }, "name": { "type": "string", "description": "", "example": "1 TL Gpay Epin" }, "price": { "type": "number", "description": "E-pin fiyatı (TL)", "example": 1 }, "sell_price": { "type": "number", "description": "Gold satış fiyatı (TL)" }, "in_stock": { "type": "boolean", "description": "stock > 0", "example": true }, "stock": { "type": "integer", "enum": [ 0, 1 ], "example": 1, "description": "Stok: 0 = yok, 1 = var. Adet veya seviye bilgisi verilmez." }, "status": { "type": "string", "description": "", "example": "active" }, "type": { "type": "string", "enum": [ "normal", "virtual", "topup" ], "description": "E-pin teslim tipi", "example": "normal" }, "max_buy": { "type": "integer", "description": "E-pin: tek siparişte azami adet (0 = ürün tanımı)", "example": 10 }, "min_sell": { "type": "integer", "description": "Gold: asgari adet" }, "max_sell": { "type": "integer", "description": "Gold: azami adet (0 = sınırsız)" } } }, "example": { "success": true, "product_id": 262, "name": "1 TL Gpay Epin", "price": 1, "in_stock": true, "stock": 1, "status": "active", "type": "normal", "max_buy": 10 } } } }, "401": { "description": "Kimlik/yetki hatası (token yok, süresi dolmuş, scope yetersiz, IP izinsiz). HTTP gövdesi 200 dönebilir; `success:false` ve `message` alanına bakın.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "429": { "description": "İstek limiti aşıldı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product_type": { "type": "string", "enum": [ "epin", "gold" ], "description": "", "example": "epin" }, "product_id": { "type": "integer", "description": "", "example": 262 } }, "required": [ "product_type", "product_id" ] }, "example": { "product_type": "epin", "product_id": 262 } } } } } }, "/stock-multi": { "post": { "tags": [ "3 · Stok" ], "summary": "Toplu stok (≤50)", "description": "Tek istekte en fazla 50 ürünün stok durumunu döner. **Scope:** `gold` veya `epin`.", "operationId": "post_stock_multi", "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "count": { "type": "integer", "description": "", "example": 2 }, "products": { "type": "array", "description": "", "items": { "type": "object", "properties": { "product_type": { "type": "string", "enum": [ "epin", "gold" ], "description": "" }, "product_id": { "type": "integer", "description": "" }, "name": { "type": "string", "description": "" }, "price": { "type": "number", "description": "" }, "sell_price": { "type": "number", "description": "" }, "in_stock": { "type": "boolean", "description": "" }, "stock": { "type": "integer", "enum": [ 0, 1 ], "example": 1, "description": "Stok: 0 = yok, 1 = var. Adet veya seviye bilgisi verilmez." }, "error": { "type": "string", "description": "Ürün bulunamadı / aktif değil" } } } } } } } } }, "401": { "description": "Kimlik/yetki hatası (token yok, süresi dolmuş, scope yetersiz, IP izinsiz). HTTP gövdesi 200 dönebilir; `success:false` ve `message` alanına bakın.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "429": { "description": "İstek limiti aşıldı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "description": "En fazla 50", "items": { "type": "object", "properties": { "product_type": { "type": "string", "enum": [ "epin", "gold" ], "description": "" }, "product_id": { "type": "integer", "description": "" } } } } }, "required": [ "products" ] }, "example": { "products": [ { "product_type": "epin", "product_id": 262 }, { "product_type": "gold", "product_id": 13 } ] } } } } } }, "/stock-all": { "post": { "tags": [ "3 · Stok" ], "summary": "Tüm ürünlerin stok durumu", "description": "Aktif tüm ürünlerin stok durumunu (var/yok) tek çağrıda döner; periyodik senkron için önerilen uç. **Scope:** `gold` veya `epin`.", "operationId": "post_stock_all", "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "count": { "type": "integer", "description": "", "example": 1203 }, "products": { "type": "array", "description": "", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "epin", "gold" ], "description": "" }, "product_id": { "type": "integer", "description": "", "example": 3 }, "name": { "type": "string", "description": "", "example": "Bronze Premium" }, "stock": { "type": "integer", "enum": [ 0, 1 ], "example": 1, "description": "Stok: 0 = yok, 1 = var. Adet veya seviye bilgisi verilmez." } } } } } } } } }, "401": { "description": "Kimlik/yetki hatası (token yok, süresi dolmuş, scope yetersiz, IP izinsiz). HTTP gövdesi 200 dönebilir; `success:false` ve `message` alanına bakın.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "429": { "description": "İstek limiti aşıldı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "product_type": { "type": "string", "enum": [ "epin", "gold" ], "description": "Boş = tümü" } } } } } } } }, "/check-user": { "post": { "tags": [ "4 · Sipariş" ], "summary": "Top-up kullanıcı doğrulama", "description": "Doğrudan yükleme (top-up) ürünlerinde, siparişten **önce** oyuncu/kullanıcı bilgisini doğrular; yanlış hesaba yükleme riskini azaltır. Alanlar `epinbuy` ile aynıdır: ürünün `fields` listesindeki her kod için `extra_` gönderilir (ör. `extra_joygameusername`). Desteklenen sağlayıcıda `valid` ve bulunan kullanıcı bilgisi döner; ön doğrulama olmayan ürün/sağlayıcıda `supported:false` döner ve sipariş yine verilebilir. **Scope:** `epin`.", "operationId": "post_check_user", "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "product_epin_id": { "type": "integer", "description": "", "example": 13 }, "provider": { "type": "string", "description": "Teslimat sağlayıcısı", "example": "perdigital" }, "fields": { "type": "array", "description": "Bu ürünün istediği alan kodları", "items": { "type": "string" } }, "supported": { "type": "boolean", "description": "Ön doğrulama destekleniyor mu", "example": true }, "valid": { "type": "boolean", "description": "Kullanıcı bulundu mu (supported=true iken)", "example": true }, "user": { "type": "object", "properties": { "username": { "type": "string", "description": "", "example": "oyuncu_adi" }, "user_id": { "type": "string", "description": "", "example": "736517" }, "zone_id": { "type": "string", "description": "" }, "level": { "type": "string", "description": "" }, "clan": { "type": "string", "description": "" } } }, "message": { "type": "string", "description": "", "example": "Kullanici dogrulandi" } } }, "example": { "success": true, "product_epin_id": 13, "provider": "perdigital", "fields": [ "joygameusername" ], "supported": true, "valid": true, "user": { "username": "oyuncu_adi", "user_id": "736517" }, "message": "Kullanici dogrulandi" } } } }, "401": { "description": "Kimlik/yetki hatası (token yok, süresi dolmuş, scope yetersiz, IP izinsiz). HTTP gövdesi 200 dönebilir; `success:false` ve `message` alanına bakın.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "429": { "description": "İstek limiti aşıldı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product_epin_id": { "type": "integer", "description": "", "example": 13 }, "extra_joygameusername": { "type": "string", "description": "Ürüne göre değişen alan(lar): `extra_`", "example": "oyuncu_adi" } }, "required": [ "product_epin_id" ] }, "example": { "product_epin_id": 13, "extra_joygameusername": "oyuncu_adi" } } } } } }, "/epinbuy": { "post": { "tags": [ "4 · Sipariş" ], "summary": "E-pin satın al", "description": "E-pin satın alır. Normal e-pinlerde kodlar **yanıtta anında** teslim edilir; sanal/top-up ürünlerde `status: pending` döner, sonuç `order-status` veya webhook ile izlenir. **Scope:** `epin`.\n\n**Idempotency:** `transid` sizin tekil işlem kimliğinizdir (≤70 karakter). Aynı `transid` ile tekrar istek yeni sipariş OLUŞTURMAZ; mevcut `order_id` ile `success:false` döner. Ağ hatasında aynı `transid` ile güvenle tekrar deneyin.\n\n**Sandbox:** hesabınız sandbox modundaysa gerçek sipariş ve bakiye hareketi olmaz; `sandbox-…` id ve `TEST-…` kodlar döner.", "operationId": "post_epinbuy", "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "order_id": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Sipariş no. Sandbox hesapta `sandbox-…` ön ekli metin.", "example": 2231763 }, "transid": { "type": "string", "description": "Sipariş verirken gönderdiğiniz işlem kimliği", "example": "ORDER-2026-000123" }, "status": { "type": "string", "enum": [ "success", "pending", "cancel" ], "description": "success = teslim edildi · pending = işleniyor (gold / sanal e-pin) · cancel = iptal edildi", "example": "success" }, "order_price": { "type": "number", "description": "Birim fiyat (TL)", "example": 1 }, "order_total": { "type": "number", "description": "Toplam (TL)", "example": 1 }, "sandbox": { "type": "boolean", "description": "Yalnız sandbox hesapta döner; gerçek sipariş ve bakiye hareketi OLMAZ", "example": true }, "message": { "type": "string", "description": "Bilgi mesajı", "example": "Islem Basarili" }, "codes": { "type": "array", "description": "Teslim edilen e-pin kodları (yalnız status = success). order-status ile yeniden alınabilir.", "items": { "type": "string", "example": "ABCD-EFGH-IJKL-MNOP" } } } }, "example": { "success": true, "order_id": 2231763, "transid": "ORDER-2026-000123", "status": "success", "order_price": 1, "order_total": 1, "codes": [ "ABCD-EFGH-IJKL-MNOP" ], "message": "Islem Basarili" } } } }, "402": { "description": "Bakiye yetersiz", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientBalance" } } } }, "401": { "description": "Kimlik/yetki hatası (token yok, süresi dolmuş, scope yetersiz, IP izinsiz). HTTP gövdesi 200 dönebilir; `success:false` ve `message` alanına bakın.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "429": { "description": "İstek limiti aşıldı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product_epin_id": { "type": "integer", "description": "", "example": 262 }, "quantity": { "type": "integer", "description": "≥1, ürünün azami adedine kadar", "example": 1 }, "transid": { "type": "string", "description": "Tekil işlem kimliğiniz", "example": "ORDER-2026-000123" } }, "required": [ "product_epin_id", "quantity", "transid" ] }, "example": { "product_epin_id": 262, "quantity": 1, "transid": "ORDER-2026-000123" } } } } } }, "/goldbuy": { "post": { "tags": [ "4 · Sipariş" ], "summary": "Gold satın al", "description": "Gold siparişi oluşturur. Teslimat operatör onayıyla tamamlanır; `status: pending` ile döner, sonuç `order-status` veya webhook ile izlenir. **Scope:** `gold`.\n\n**Idempotency:** `transid` sizin tekil işlem kimliğinizdir (≤70 karakter). Aynı `transid` ile tekrar istek yeni sipariş OLUŞTURMAZ; mevcut `order_id` ile `success:false` döner. Ağ hatasında aynı `transid` ile güvenle tekrar deneyin.\n\n**Sandbox:** hesabınız sandbox modundaysa gerçek sipariş ve bakiye hareketi olmaz; `sandbox-…` id ve `TEST-…` kodlar döner.", "operationId": "post_goldbuy", "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "order_id": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Sipariş no. Sandbox hesapta `sandbox-…` ön ekli metin.", "example": 2231763 }, "transid": { "type": "string", "description": "Sipariş verirken gönderdiğiniz işlem kimliği", "example": "ORDER-2026-000123" }, "status": { "type": "string", "enum": [ "success", "pending", "cancel" ], "description": "success = teslim edildi · pending = işleniyor (gold / sanal e-pin) · cancel = iptal edildi", "example": "success" }, "order_price": { "type": "number", "description": "Birim fiyat (TL)", "example": 1 }, "order_total": { "type": "number", "description": "Toplam (TL)", "example": 1 }, "sandbox": { "type": "boolean", "description": "Yalnız sandbox hesapta döner; gerçek sipariş ve bakiye hareketi OLMAZ", "example": true }, "message": { "type": "string", "description": "Bilgi mesajı", "example": "Islem Basarili" }, "character": { "type": "string", "description": "", "example": "KnightAhmet" } } }, "example": { "success": true, "order_id": 2231764, "transid": "ORDER-2026-000124", "status": "pending", "order_price": 8, "order_total": 16, "character": "KnightAhmet", "message": "Islem Basarili" } } } }, "402": { "description": "Bakiye yetersiz", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientBalance" } } } }, "401": { "description": "Kimlik/yetki hatası (token yok, süresi dolmuş, scope yetersiz, IP izinsiz). HTTP gövdesi 200 dönebilir; `success:false` ve `message` alanına bakın.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "429": { "description": "İstek limiti aşıldı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product_gold_id": { "type": "integer", "description": "", "example": 13 }, "quantity": { "type": "integer", "description": "", "example": 2 }, "customerchar": { "type": "string", "description": "Teslimat yapılacak oyun karakteri", "example": "KnightAhmet" }, "transid": { "type": "string", "description": "", "example": "ORDER-2026-000124" } }, "required": [ "product_gold_id", "quantity", "customerchar", "transid" ] }, "example": { "product_gold_id": 13, "quantity": 2, "customerchar": "KnightAhmet", "transid": "ORDER-2026-000124" } } } } } }, "/order-status": { "post": { "tags": [ "4 · Sipariş" ], "summary": "Sipariş durumu ve kodlar", "description": "Sipariş durumunu ve (e-pin ise) teslim edilmiş kodları döner. `order_id` **veya** `transid` ile sorgulanır. Yalnız kendi siparişleriniz görünür. **Scope:** `gold` veya `epin`.", "operationId": "post_order_status", "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "order_id": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Sipariş no. Sandbox hesapta `sandbox-…` ön ekli metin.", "example": 2231763 }, "transid": { "type": "string", "description": "Sipariş verirken gönderdiğiniz işlem kimliği", "example": "ORDER-2026-000123" }, "status": { "type": "string", "enum": [ "success", "pending", "cancel" ], "description": "success = teslim edildi · pending = işleniyor (gold / sanal e-pin) · cancel = iptal edildi", "example": "success" }, "status_detail": { "type": "string", "enum": [ "processing", "delivering", "delivered", "cancelled" ], "description": "Ayrıntılı durum: processing = işleniyor · delivering = teslimatta (operatör işleme aldı) · delivered = teslim edildi · cancelled = iptal", "example": "delivered" }, "reason": { "type": "string", "description": "İptal nedeni (yalnız iptalde, aksi hâlde null)" }, "created_at": { "type": "string", "description": "Oluşturulma zamanı (Europe/Istanbul)", "example": "2026-10-02 22:40:38" }, "type": { "type": "string", "enum": [ "epin", "gold" ], "description": "Ürün tipi", "example": "epin" }, "quantity": { "type": "integer", "description": "Adet", "example": 1 }, "total": { "type": "number", "description": "Toplam tutar (TL)", "example": 1 }, "codes": { "type": "array", "description": "Teslim edilen e-pin kodları (yalnız status = success). order-status ile yeniden alınabilir.", "items": { "type": "string", "example": "ABCD-EFGH-IJKL-MNOP" } }, "character": { "type": "string", "description": "Gold: karakter adı" }, "items": { "type": "array", "description": "Kalem bazlı ayrıntı", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "epin", "gold" ], "description": "Kalem tipi", "example": "epin" }, "product_id": { "type": "integer", "description": "Ürün ID", "example": 262 }, "status": { "type": "string", "enum": [ "success", "pending", "cancel" ], "description": "success = teslim edildi · pending = işleniyor (gold / sanal e-pin) · cancel = iptal edildi", "example": "success" }, "status_detail": { "type": "string", "enum": [ "processing", "delivering", "delivered", "cancelled" ], "description": "Ayrıntılı durum: processing = işleniyor · delivering = teslimatta (operatör işleme aldı) · delivered = teslim edildi · cancelled = iptal", "example": "delivered" }, "reason": { "type": "string", "description": "İptal nedeni (yalnız iptalde, aksi hâlde null)" }, "quantity": { "type": "integer", "description": "Adet", "example": 1 }, "total": { "type": "number", "description": "Toplam tutar (TL)", "example": 1 }, "codes": { "type": "array", "description": "Teslim edilen e-pin kodları (yalnız status = success). order-status ile yeniden alınabilir.", "items": { "type": "string", "example": "ABCD-EFGH-IJKL-MNOP" } }, "character": { "type": "string", "description": "Gold: karakter adı", "example": "KnightAhmet" } } } } } }, "example": { "success": true, "order_id": 2231763, "transid": "ORDER-2026-000123", "status": "success", "created_at": "2026-10-02 22:40:38", "type": "epin", "quantity": 1, "total": 1, "codes": [ "ABCD-EFGH-IJKL-MNOP" ], "items": [ { "type": "epin", "product_id": 262, "status": "success", "quantity": 1, "total": 1, "codes": [ "ABCD-EFGH-IJKL-MNOP" ] } ] } } } }, "401": { "description": "Kimlik/yetki hatası (token yok, süresi dolmuş, scope yetersiz, IP izinsiz). HTTP gövdesi 200 dönebilir; `success:false` ve `message` alanına bakın.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "429": { "description": "İstek limiti aşıldı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "order_id": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Sipariş no (sandbox id olabilir)", "example": 2231763 }, "transid": { "type": "string", "description": "", "example": "ORDER-2026-000123" } } }, "example": { "transid": "ORDER-2026-000123" } } } } } }, "/order-list": { "post": { "tags": [ "4 · Sipariş" ], "summary": "Sipariş listesi (tarih aralığı)", "description": "API siparişlerinizi tarih aralığına göre sayfalı listeler (kod içermez; kodlar için `order-status`). Tarih verilmezse **son 24 saat** döner. Verilirse `YYYY-MM-DD`, aralık en fazla **30 gün**; `end_date` boşsa `start_date` günü. Sayfa başına en fazla 100 kayıt. **Scope:** `gold` veya `epin`.", "operationId": "post_order_list", "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "from": { "type": "string", "description": "Uygulanan aralık başı", "example": "2026-10-01 00:00:00" }, "to": { "type": "string", "description": "", "example": "2026-10-03 23:59:59" }, "total": { "type": "integer", "description": "", "example": 2 }, "page": { "type": "integer", "description": "", "example": 1 }, "limit": { "type": "integer", "description": "", "example": 50 }, "orders": { "type": "array", "description": "", "items": { "type": "object", "properties": { "order_id": { "type": "integer", "description": "", "example": 2232571 }, "transid": { "type": "string", "description": "", "example": "E2E-1791008645" }, "type": { "type": "string", "enum": [ "epin", "gold" ], "description": "" }, "product_id": { "type": "integer", "description": "", "example": 262 }, "name": { "type": "string", "description": "", "example": "1 TL Gpay Epin" }, "quantity": { "type": "integer", "description": "", "example": 1 }, "total": { "type": "number", "description": "", "example": 1 }, "status": { "type": "string", "enum": [ "success", "pending", "cancel" ], "description": "success = teslim edildi · pending = işleniyor (gold / sanal e-pin) · cancel = iptal edildi", "example": "success" }, "status_detail": { "type": "string", "enum": [ "processing", "delivering", "delivered", "cancelled" ], "description": "", "example": "delivered" }, "reason": { "type": "string", "description": "İptal nedeni" }, "created_at": { "type": "string", "description": "", "example": "2026-10-03 09:24:25" }, "character": { "type": "string", "description": "Gold" } } } } } }, "example": { "success": true, "from": "2026-10-01 00:00:00", "to": "2026-10-03 23:59:59", "total": 1, "page": 1, "limit": 50, "orders": [ { "order_id": 2232571, "transid": "E2E-1791008645", "type": "epin", "product_id": 262, "name": "1 TL Gpay Epin", "quantity": 1, "total": 1, "status": "success", "status_detail": "delivered", "reason": null, "created_at": "2026-10-03 09:24:25" } ] } } } }, "401": { "description": "Kimlik/yetki hatası (token yok, süresi dolmuş, scope yetersiz, IP izinsiz). HTTP gövdesi 200 dönebilir; `success:false` ve `message` alanına bakın.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "429": { "description": "İstek limiti aşıldı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "start_date": { "type": "string", "description": "YYYY-MM-DD (opsiyonel)", "example": "2026-10-01" }, "end_date": { "type": "string", "description": "YYYY-MM-DD (opsiyonel)", "example": "2026-10-03" }, "type": { "type": "string", "enum": [ "epin", "gold" ], "description": "Boş = tümü" }, "status": { "type": "string", "enum": [ "success", "pending", "cancel" ], "description": "Boş = tümü" }, "page": { "type": "integer", "description": "", "example": 1 }, "limit": { "type": "integer", "description": "≤100", "example": 50 } } }, "example": { "start_date": "2026-10-01", "end_date": "2026-10-03", "page": 1, "limit": 50 } } } } } }, "/order-cancel": { "post": { "tags": [ "4 · Sipariş" ], "summary": "Sipariş iptal", "description": "Yalnız **henüz işleme alınmamış** (`pending`) gold siparişleri iptal edilir; bakiye iade edilir. Teslim edilmiş e-pin siparişleri iptal **edilemez**. **Scope:** `gold` veya `epin`.", "operationId": "post_order_cancel", "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "order_id": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "", "example": 2231764 }, "status": { "type": "string", "description": "", "example": "cancel" }, "refunded": { "type": "number", "description": "İade edilen tutar (TL)", "example": 16 }, "message": { "type": "string", "description": "" } } } } } }, "401": { "description": "Kimlik/yetki hatası (token yok, süresi dolmuş, scope yetersiz, IP izinsiz). HTTP gövdesi 200 dönebilir; `success:false` ve `message` alanına bakın.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "429": { "description": "İstek limiti aşıldı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "order_id": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "", "example": 2231764 } }, "required": [ "order_id" ] }, "example": { "order_id": 2231764 } } } } } }, "/webhook-test": { "post": { "tags": [ "5 · Webhook" ], "summary": "Webhook testi gönder", "description": "Panelde tanımlı webhook (ping) URL'inize gerçek bildirimle **aynı imza şemasıyla** `event: \"test\"` gönderir. Yerel/özel IP'lere gönderim engellidir. **Scope:** `me`.", "operationId": "post_webhook_test", "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "webhook_url": { "type": "string", "description": "", "example": "https://bayi.example.com/kopazar-webhook" }, "http_code": { "type": "integer", "description": "", "example": 200 }, "response": { "type": "string", "description": "İlk 500 karakter", "example": "OK" }, "error": { "type": "string", "description": "" }, "payload_sent": { "type": "object", "properties": {} } } } } } }, "401": { "description": "Kimlik/yetki hatası (token yok, süresi dolmuş, scope yetersiz, IP izinsiz). HTTP gövdesi 200 dönebilir; `success:false` ve `message` alanına bakın.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "429": { "description": "İstek limiti aşıldı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } } } }, "/webhook-logs": { "post": { "tags": [ "5 · Webhook" ], "summary": "Webhook teslimat kayıtları", "description": "Webhook teslimat denemelerini sayfalı listeler (en fazla 100/sayfa). **Scope:** `me`.", "operationId": "post_webhook_logs", "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "total": { "type": "integer", "description": "" }, "page": { "type": "integer", "description": "" }, "limit": { "type": "integer", "description": "" }, "logs": { "type": "array", "description": "", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "" }, "status": { "type": "string", "description": "" }, "attempts": { "type": "integer", "description": "" }, "created_at": { "type": "string", "description": "" }, "response": { "type": "string", "description": "" }, "curl_error": { "type": "string", "description": "" } } } } } } } } }, "401": { "description": "Kimlik/yetki hatası (token yok, süresi dolmuş, scope yetersiz, IP izinsiz). HTTP gövdesi 200 dönebilir; `success:false` ve `message` alanına bakın.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "429": { "description": "İstek limiti aşıldı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "page": { "type": "integer", "description": "", "example": 1 }, "limit": { "type": "integer", "description": "", "example": 50 } } } } } } } }, "/me": { "get": { "tags": [ "6 · Hesap" ], "summary": "Hesap bilgisi ve bakiye", "description": "Bayi hesabının ad/soyad, maskeli e-posta/GSM ve kullanılabilir bakiyesini döner. **Scope:** `me`.", "operationId": "get_me", "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "name": { "type": "string", "description": "", "example": "MEHMET" }, "surname": { "type": "string", "description": "", "example": "U***" }, "mail": { "type": "string", "description": "Maskeli", "example": "me****@kopazar.com" }, "gsm": { "type": "string", "description": "Maskeli", "example": "532***562" }, "credit": { "type": "number", "description": "Bakiye (TL)", "example": 162420 }, "bonus": { "type": "number", "description": "Bonus bakiye (TL)", "example": 0 }, "spent_today": { "type": "number", "description": "Bugünkü API siparişleri toplamı (TL)", "example": 1 }, "spent_month": { "type": "number", "description": "Bu ayki API siparişleri toplamı (TL)", "example": 2 } } } } } }, "401": { "description": "Kimlik/yetki hatası (token yok, süresi dolmuş, scope yetersiz, IP izinsiz). HTTP gövdesi 200 dönebilir; `success:false` ve `message` alanına bakın.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "429": { "description": "İstek limiti aşıldı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } } } }, "/limits": { "get": { "tags": [ "6 · Hesap" ], "summary": "Limitler ve kullanım", "description": "Hesabınıza tanımlı istek limitleri ile günlük/aylık satış limitlerini ve kullanımını döner. **Scope:** `me`.", "operationId": "get_limits", "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "rate_limits": { "type": "object", "properties": { "requests_per_minute": { "type": "integer", "description": "Hesap profiline göre: alışveriş hesabı varsayılan 120, fiyat-only hesap 2", "example": 120 }, "requests_per_hour": { "type": "integer", "description": "Alışveriş 3000 / fiyat-only 60 (varsayılan)", "example": 3000 }, "buy_per_minute": { "type": "integer", "description": "Dakikada satın alma", "example": 10 } } }, "sales_limits": { "type": "object", "properties": { "daily_limit": { "type": "number", "description": "0 = limitsiz", "example": 0 }, "daily_used": { "type": "number", "description": "", "example": 0 }, "daily_remaining": { "type": "number", "description": "", "example": 0 }, "monthly_limit": { "type": "number", "description": "", "example": 0 }, "monthly_used": { "type": "number", "description": "", "example": 0 }, "monthly_remaining": { "type": "number", "description": "", "example": 0 } } }, "sandbox_mode": { "type": "boolean", "description": "", "example": false } } } } } }, "401": { "description": "Kimlik/yetki hatası (token yok, süresi dolmuş, scope yetersiz, IP izinsiz). HTTP gövdesi 200 dönebilir; `success:false` ve `message` alanına bakın.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "429": { "description": "İstek limiti aşıldı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } } } }, "/ip-manage": { "post": { "tags": [ "7 · Hesap Yönetimi" ], "summary": "IP beyaz listesi", "description": "Hesabınızın 4 slotluk IP beyaz listesini yönetir. Liste doluysa token ve tüm çağrılar yalnız bu IP'lerden kabul edilir. **Scope:** `me`.", "operationId": "post_ip_manage", "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "ips": { "type": "array", "description": "", "items": { "type": "object", "properties": { "slot": { "type": "integer", "description": "", "example": 1 }, "ip": { "type": "string", "description": "", "example": "203.0.113.10" } } } }, "max_slots": { "type": "integer", "description": "", "example": 4 }, "message": { "type": "string", "description": "" } } } } } }, "401": { "description": "Kimlik/yetki hatası (token yok, süresi dolmuş, scope yetersiz, IP izinsiz). HTTP gövdesi 200 dönebilir; `success:false` ve `message` alanına bakın.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "429": { "description": "İstek limiti aşıldı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "list", "add", "remove" ], "description": "", "example": "add" }, "ip": { "type": "string", "description": "add/remove için zorunlu", "example": "203.0.113.10" } }, "required": [ "action" ] }, "example": { "action": "add", "ip": "203.0.113.10" } } } } } }, "/rotate-key": { "post": { "tags": [ "7 · Hesap Yönetimi" ], "summary": "Client secret / salt yenile", "description": "Client secret ve webhook imza anahtarını (salt) yeniler. **Dikkat:** eski webhook imzaları geçersiz olur; bayi tarafındaki doğrulama anahtarını güncelleyin. Mevcut tüm erişim ve yenileme token'ları da anında iptal edilir (`AUTH_TOKEN_REVOKED`); `/token` ile yeniden giriş yapın. **Scope:** `me`.", "operationId": "post_rotate_key", "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "new_client_secret": { "type": "string", "description": "" }, "new_salt": { "type": "string", "description": "Yeni webhook imza anahtarı" }, "client_id": { "type": "string", "description": "" }, "warning": { "type": "string", "description": "" }, "message": { "type": "string", "description": "" } } } } } }, "401": { "description": "Kimlik/yetki hatası (token yok, süresi dolmuş, scope yetersiz, IP izinsiz). HTTP gövdesi 200 dönebilir; `success:false` ve `message` alanına bakın.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "429": { "description": "İstek limiti aşıldı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirm": { "type": "boolean", "description": "Onay için true", "example": true } }, "required": [ "confirm" ] }, "example": { "confirm": true } } } } } }, "/usage-stats": { "post": { "tags": [ "7 · Hesap Yönetimi" ], "summary": "Kullanım istatistikleri", "description": "Seçilen dönem için API çağrı istatistiklerinizi (toplam, uç bazlı, günlük) ve limitlerinizi döner. **Scope:** `me`.", "operationId": "post_usage_stats", "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "period": { "type": "string", "description": "" }, "overview": { "type": "object", "properties": {} }, "by_endpoint": { "type": "array", "description": "", "items": { "type": "object", "properties": {} } }, "daily": { "type": "array", "description": "", "items": { "type": "object", "properties": {} } }, "limits": { "type": "object", "properties": {} } } } } } }, "401": { "description": "Kimlik/yetki hatası (token yok, süresi dolmuş, scope yetersiz, IP izinsiz). HTTP gövdesi 200 dönebilir; `success:false` ve `message` alanına bakın.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "429": { "description": "İstek limiti aşıldı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "period": { "type": "string", "enum": [ "today", "week", "month" ], "description": "", "example": "week" } } }, "example": { "period": "week" } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "`POST /token` ile alınan access_token" } }, "schemas": { "Error": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error_code": { "type": "string", "example": "PRODUCT_NOT_FOUND", "description": "Makine-okur hata kodu (sabit İngilizce anahtar); liste için üstteki \"Hata kodları\" bölümü" }, "message": { "type": "string", "description": "Açıklayıcı hata mesajı", "example": "Urun bulunamadi" } } }, "AuthError": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error_code": { "type": "string", "example": "AUTH_TOKEN_EXPIRED", "description": "Makine-okur hata kodu (sabit İngilizce anahtar); liste için üstteki \"Hata kodları\" bölümü" }, "message": { "type": "string", "description": "", "example": "Token suresi dolmus" } } }, "RateLimitError": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error_code": { "type": "string", "example": "RATE_LIMITED", "description": "Makine-okur hata kodu (sabit İngilizce anahtar); liste için üstteki \"Hata kodları\" bölümü" }, "message": { "type": "string", "description": "", "example": "Rate limit asildi. Limit: 120/minute" } } }, "InsufficientBalance": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error_code": { "type": "string", "example": "BALANCE_INSUFFICIENT", "description": "Makine-okur hata kodu (sabit İngilizce anahtar); liste için üstteki \"Hata kodları\" bölümü" }, "message": { "type": "string", "description": "", "example": "Krediniz yetersiz" } } } } } }