{ "openapi": "3.1.0", "info": { "title": "Oyuneks Bayi API", "version": "1.0.0", "summary": "Oyuneks bayileri için toptan e-pin ve top-up sipariş yüzeyi.", "description": "Katalog ve bayi fiyatlarınızı çekin, oyuncu hesabını doğrulayın, sipariş verin, kodu saniyeler içinde alın. Bakiye ve cari hareketleriniz aynı API'de. Fiyat, stok ve teslim değişiklikleri size imzalı webhook ile gelir.\nBayi Paneli ile API AYNI çekirdeği kullanır: iki kanal hiçbir zaman farklı fiyat, farklı stok ya da farklı hata göstermez. Panelde gördüğünüz sayı, API'nin döndürdüğü sayıdır.\n\n## Genel kurallar\n- Başarı zarfı her uçta aynı: {\"data\": ..., \"mode\": \"live|test\", \"requestId\": \"...\"}. Hata zarfı: {\"error\":{\"code\",\"message\",\"retryable\",\"requestId\",\"details\"}}.\n- Para alanları METİN ve nokta ondalıklı: \"411.50\". Kayan noktalı sayı JSON'da 411.5 olur ve bazı istemcilerde 411.49999 görünür; muhasebe eşleşmesi bozulur. Para birimi her yerde TRY.\n- Tarihler ISO-8601 ve Türkiye saati: \"2026-08-28T14:05:00+03:00\".\n- Listeler İMLEÇLİ sayfalanır: yanıttaki nextCursor değerini ?cursor= ile geri gönderin. limit en çok 200 (sipariş listesinde 100). OFFSET sayfalama yoktur; araya yeni kayıt girdiğinde kalem atlar ya da tekrarlar.\n- Her yanıtta X-Request-Id başlığı vardır; destek yazışmasında bu numarayı verin, istek tek sorguyla bulunur.\n- Katalog uçları ETag döner; If-None-Match gönderirseniz gövde değişmediyse 304 alırsınız (gövde harcanmaz).\n- Zorunlu alanlar (oyuncu ID, sunucu, karakter...) fields nesnesinde, ürünün requiredFields şemasına göre gönderilir. SIRA DEĞİL ANAHTAR ADI önemlidir.\n- Bilinmeyen bir alan gönderirseniz yok sayılır; bilinmeyen bir OLAY adı gönderirseniz 400 alırsınız (sessizce düşürmek \"abone oldum\" yanılgısı yaratırdı).\n\n## Yetki kapsamları\n- `catalog:read` — Katalog ve fiyat okuma\n- `orders:read` — Siparisleri ve kodlari okuma\n- `orders:write` — Siparis verme ve iptal (bakiyeden para duser)\n- `balance:read` — Bakiye ve cari hareket okuma\n- `webhooks:manage` — Webhook aboneligi yonetimi", "contact": { "name": "Oyuneks", "url": "https://oyuneks.com/bayi-api/docs" }, "x-api-version": "v1", "x-changelog": [ { "date": "28.08.2026", "version": "v1", "title": "Bayi API yayinda", "notes": [ "Katalog, bayi fiyati, stok ve zorunlu alan semasi uclari.", "Siparis verme (Idempotency-Key zorunlu), okuma, referansla arama ve bekleyen kalem iptali.", "Bakiye, cari hareket, donem ekstresi (json/csv) ve fatura listesi.", "Imzali webhook aboneligi: 8 olay + ping testi, gonderim kaydi, imza yenileme.", "Test anahtari (oyxb_test_): gercek katalog, gercek akis, para dusmez, TEST- onekli kod doner.", "Bu dokuman, OpenAPI 3.1 ve Postman koleksiyonu ayni kaynaktan uretiliyor.", "MCP sunucusu (/bayi-api/mcp): yapay zeka istemcileri icin 11 arac. Para harcayan araclar iki adimli onay ister." ] } ] }, "externalDocs": { "url": "https://oyuneks.com/bayi-api/docs", "description": "İnsan dokümantasyonu" }, "servers": [ { "url": "https://oyuneks.com/bayi-api/v1", "description": "Canlı. Test modu AYNI adrestedir: oyxb_test_ önekli anahtar kullanın." } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Hesap & bakiye", "description": "Anahtarın hangi hesaba bağlı olduğu, limitler ve para." }, { "name": "Katalog & fiyat", "description": "Ürün kimliği, bayi fiyatınız, stok ve zorunlu alan şeması. Kimlik ve alan adı UYDURULMAZ, hep buradan okunur." }, { "name": "Hesap doğrulama", "description": "Top-up ürünlerinde oyuncu bilgisini yüklemeden ÖNCE sorun." }, { "name": "Sipariş", "description": "Sipariş verme, okuma ve bekleyen kalem iptali. Panel ile API AYNI çekirdeği kullanır: iki kanal hiçbir zaman farklı fiyat/stok/hata göstermez." }, { "name": "Raporlar", "description": "Ekstre ve fatura. Panel ekstresi, API ekstresi ve fatura AYNI rakamları verir." }, { "name": "Webhook'lar", "description": "Yoklamayı (polling) bırakın: sipariş sonucu, fiyat değişimi ve bakiye yüklemesi imzalı olay olarak size gelir. Bayi başına TEK adres olduğu için PUT /webhooks bir \"upsert\"tir." } ], "paths": { "/me": { "get": { "operationId": "me", "summary": "Anahtar sağlık kontrolü", "description": "Bayi kimliği, firma adı, kademe, kullanılabilir bakiye, günlük limit ve anahtarın kapsamları. mode alanı \"live\" ya da \"test\" döner; entegrasyonun ilk isteği bu olmalı. Kapsam İSTEMEZ: hangi kapsamla üretilmiş olursa olsun geçerli her anahtar kendini doğrulayabilir.", "tags": [ "Hesap & bakiye" ], "x-oyuneks-scope": "(herhangi)", "responses": { "200": { "description": "Başarılı", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "mode" ], "properties": { "data": { "$ref": "#/components/schemas/Me" }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "requestId": { "type": "string", "maxLength": 26 } } }, "example": { "data": { "dealerId": 385841, "company": "ÖRNEK BİLİŞİM LTD. ŞTİ.", "tier": "Bronz", "tierId": 1, "balance": "48250.00", "currency": "TRY", "limits": { "dailyPurchase": "250000.00", "dailyUsed": "1200.00", "maxQtyPerOrder": 500 }, "apiEnabled": true, "key": { "name": "Canlı anahtar", "masked": "oyxb_live_a91f...3c0e", "scopes": [ "catalog:read", "orders:read", "orders:write", "balance:read" ], "rateReadPerMin": 300, "rateWritePerMin": 60 }, "apiVersion": "v1", "serverTime": "2026-08-28T14:05:00+03:00" }, "mode": "live", "requestId": "01K3QF6ZC2M9V0X7NB4TDHR8YE" } } } }, "401": { "$ref": "#/components/responses/Yetkisiz" }, "403": { "$ref": "#/components/responses/Yasak" }, "429": { "$ref": "#/components/responses/TavanAsimi" }, "500": { "$ref": "#/components/responses/IcHata" }, "503": { "$ref": "#/components/responses/Kapali" } } } }, "/balance": { "get": { "operationId": "balance", "summary": "Kullanılabilir bakiye", "description": "Kullanılabilir bakiye, bloke tutar, onay bekleyen havale toplamı ve kırılım (bakiye + iade edilebilir + bonus). available değeri SİPARİŞ KAPISININ okuduğu ile aynı sayıdır; başka bir toplama yazılsa bot \"param var\" der ama sipariş INSUFFICIENT_BALANCE yerdi.", "tags": [ "Hesap & bakiye" ], "x-oyuneks-scope": "balance:read", "responses": { "200": { "description": "Başarılı", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "mode" ], "properties": { "data": { "$ref": "#/components/schemas/Balance" }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "requestId": { "type": "string", "maxLength": 26 } } }, "example": { "data": { "available": "48250.00", "blocked": "0.00", "breakdown": { "balance": "46250.00", "refundable": "1500.00", "bonus": "500.00" }, "pendingDeposits": "5000.00", "currency": "TRY", "asOf": "2026-08-28T14:05:00+03:00" }, "mode": "live", "requestId": "01K3QF6ZC2M9V0X7NB4TDHR8YE" } } } }, "401": { "$ref": "#/components/responses/Yetkisiz" }, "403": { "$ref": "#/components/responses/Yasak" }, "429": { "$ref": "#/components/responses/TavanAsimi" }, "500": { "$ref": "#/components/responses/IcHata" }, "503": { "$ref": "#/components/responses/Kapali" } } } }, "/balance/transactions": { "get": { "operationId": "transactions", "summary": "Cari hareketler (imleçli)", "description": "Cari hareket defteri. Sipariş hareketlerinde tutar EKSİ işaretli döner ve orderId + externalRef alanları dolar; balanceAfter ile mutabakat yapılır. Sayfalama imleçli: yanıttaki nextCursor değerini ?cursor= ile geri gönderin.", "tags": [ "Hesap & bakiye" ], "x-oyuneks-scope": "balance:read", "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Başlangıç tarihi (dahil). Okunamayan tarih sessizce yok sayılır.", "schema": { "type": "string", "format": "date" }, "example": "2026-08-01" }, { "name": "to", "in": "query", "required": false, "description": "Bitiş tarihi (dahil).", "schema": { "type": "string", "format": "date" }, "example": "2026-08-28" }, { "name": "type", "in": "query", "required": false, "description": "Hareket tipi süzgeci. Listede olmayan tipler \"other\" döner ve typeId alanı ham değeri taşır.", "schema": { "type": "string", "enum": [ "order", "refund", "deposit", "adjustment", "other" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Önceki yanıttaki nextCursor. Yalnız rakam kabul edilir.", "schema": { "type": "string" }, "example": "3012301" }, { "name": "limit", "in": "query", "required": false, "description": "Sayfa boyu (1-200).", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "Başarılı", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "mode" ], "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Sonraki sayfa imleci; null ise sayfa bitti." }, "count": { "type": "integer" }, "note": { "type": "string", "description": "Süzgeç uygulanamadıysa nedeni." }, "currency": { "type": "string", "examples": [ "TRY" ] } } }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "requestId": { "type": "string", "maxLength": 26 } } }, "example": { "data": { "items": [ { "id": 3012402, "type": "order", "typeId": 1, "amount": "-197.40", "balanceAfter": "48052.60", "orderId": 184213, "externalRef": "SIP-2026-0001", "description": "Sipariş ödemesi", "createdAt": "2026-08-28T14:05:00+03:00" }, { "id": 3012301, "type": "deposit", "typeId": 2, "amount": "25000.00", "balanceAfter": "48250.00", "orderId": null, "externalRef": null, "description": "Havale", "createdAt": "2026-08-28T09:12:00+03:00" } ], "nextCursor": "3012301", "currency": "TRY" }, "mode": "live", "requestId": "01K3QF6ZC2M9V0X7NB4TDHR8YE" } } } }, "400": { "description": "* BAD_REQUEST — İstek biçimi hatalı: eksik alan, geçersiz değer ya da Idempotency-Key yok. Mesajı okuyup gövdeyi düzeltin; aynı istek tekrarlanırsa aynı hatayı alır.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Yetkisiz" }, "403": { "$ref": "#/components/responses/Yasak" }, "429": { "$ref": "#/components/responses/TavanAsimi" }, "500": { "$ref": "#/components/responses/IcHata" }, "503": { "$ref": "#/components/responses/Kapali" } } } }, "/catalog/games": { "get": { "operationId": "games", "summary": "Oyun listesi", "description": "Bayiye satılan ürünü olan oyunlar (üst kategoriler), her oyunun altındaki kategoriler (categories) ve ürün sayıları. Ürün listesinde category süzgecine categories[].category verilir. Ürün listesindeki game süzgecine BURADAKİ slug verilir, kategori kimliği değil: kimlikler yönetimde birleştirme sırasında değişebilir, slug adresin parçası olduğu için sabit kalmak zorundadır.", "tags": [ "Katalog & fiyat" ], "x-oyuneks-scope": "catalog:read", "parameters": [ { "name": "If-None-Match", "in": "header", "required": false, "description": "Önceki yanıtın ETag değeri. Gövde değişmediyse 304 döner.", "schema": { "type": "string" }, "example": "\"a91f3c0e\"" } ], "responses": { "200": { "description": "Başarılı", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "mode" ], "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Game" } } } }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "requestId": { "type": "string", "maxLength": 26 } } }, "example": { "data": { "items": [ { "game": "pubg-mobile", "name": "PUBG Mobile", "categoryId": 25, "productCount": 34, "categories": [ { "category": "pubg-mobile-uc", "name": "PUBG Mobile UC", "categoryId": 251, "productCount": 34 } ] }, { "game": "knight-online", "name": "Knight Online", "categoryId": 12, "productCount": 18, "categories": [] } ] }, "mode": "live", "requestId": "01K3QF6ZC2M9V0X7NB4TDHR8YE" } } } }, "304": { "description": "Değişmedi: gönderdiğiniz ETag'den bu yana gövde değişmemiş. Gövde DÖNMEZ.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Yetkisiz" }, "403": { "$ref": "#/components/responses/Yasak" }, "429": { "$ref": "#/components/responses/TavanAsimi" }, "500": { "$ref": "#/components/responses/IcHata" }, "503": { "$ref": "#/components/responses/Kapali" } } } }, "/catalog/products": { "get": { "operationId": "products", "summary": "Ürün listesi (imleçli)", "description": "Bayi fiyatı, liste fiyatı, stok durumu, adet sınırları, zorunlu alan şeması ve teslim tahmini. type=goldbar ürünlerde delivery.mode=manual gelir (kod dönmez, operatör oyun içi teslim eder) ve deliveryNote teslimat yerini yazar. price SİZİN fiyatınızdır (kademe + size özel istisna uygulanmış), listPrice sitedeki perakende fiyat. ETag döner: sonraki istekte If-None-Match ile gönderin, değişmediyse 304 alırsınız ve gövde harcanmaz.", "tags": [ "Katalog & fiyat" ], "x-oyuneks-scope": "catalog:read", "parameters": [ { "name": "type", "in": "query", "required": false, "description": "epin = kod teslim edilir, topup = oyuncu hesabına yükleme yapılır (kod yok, makbuz döner), goldbar = oyun parası (GB); karakter adına oyun içi elle teslim edilir, kod dönmez. Başka değer 400 döner.", "schema": { "type": "string", "enum": [ "epin", "topup", "goldbar" ] } }, { "name": "game", "in": "query", "required": false, "description": "Oyun slug'ı (GET /catalog/games listesinden).", "schema": { "type": "string" }, "example": "pubg-mobile" }, { "name": "category", "in": "query", "required": false, "description": "Alt kategori slug'ı (GET /catalog/games içindeki categories[].category). game ile birlikte ya da tek başına kullanılabilir.", "schema": { "type": "string" }, "example": "pubg-mobile-uc" }, { "name": "q", "in": "query", "required": false, "description": "Ürün, oyun ya da kategori adında arama.", "schema": { "type": "string" }, "example": "660 UC" }, { "name": "inStock", "in": "query", "required": false, "description": "1 gönderilirse yalnız stokta olanlar döner (\"0\", \"false\", \"no\", \"off\" ve boş değer kapalı sayılır).", "schema": { "type": "string" }, "example": "1" }, { "name": "updatedSince", "in": "query", "required": false, "description": "HENÜZ UYGULANMIYOR: üründe güncelleme damgası tutulmadığı için tam liste döner ve yanıtta note alanı bunu açıkça söyler. Artımlı senkron için ETag ya da GET /catalog/prices?since= kullanın.", "schema": { "type": "string", "format": "date-time" } }, { "name": "cursor", "in": "query", "required": false, "description": "Önceki yanıttaki nextCursor (son ürün kimliği).", "schema": { "type": "string" }, "example": "1421" }, { "name": "limit", "in": "query", "required": false, "description": "Sayfa boyu (1-200).", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "If-None-Match", "in": "header", "required": false, "description": "Önceki yanıtın ETag değeri.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Başarılı", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "mode" ], "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Sonraki sayfa imleci; null ise sayfa bitti." }, "count": { "type": "integer" }, "note": { "type": "string", "description": "Süzgeç uygulanamadıysa nedeni." } } }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "requestId": { "type": "string", "maxLength": 26 } } }, "example": { "data": { "items": [ { "productId": 6, "name": "Knight Online 1020 Cash", "type": "epin", "game": "knight-online", "category": "knight-online-cash", "region": null, "listPrice": "105.00", "price": "98.70", "currency": "TRY", "vatIncluded": true, "stock": { "mode": "count", "count": 420 }, "limits": { "minQty": 1, "maxQty": 500 }, "requiredFields": [], "delivery": { "mode": "instant", "etaSeconds": 5 }, "enabled": true, "updatedAt": null }, { "productId": 1421, "name": "PUBG Mobile 660 UC", "type": "topup", "game": "pubg-mobile", "category": "pubg-mobile-uc", "region": null, "listPrice": "428.90", "price": "411.50", "currency": "TRY", "vatIncluded": true, "stock": { "mode": "instant" }, "limits": { "minQty": 1, "maxQty": 500 }, "requiredFields": [ { "key": "playerId", "label": "Oyuncu ID", "type": "string", "minLength": 8, "maxLength": 12, "required": true, "pattern": "^.{8,12}$", "placeholder": null } ], "delivery": { "mode": "instant", "etaSeconds": 30 }, "enabled": true, "updatedAt": null } ], "nextCursor": "1421", "count": 2 }, "mode": "live", "requestId": "01K3QF6ZC2M9V0X7NB4TDHR8YE" } } } }, "304": { "description": "Değişmedi: gönderdiğiniz ETag'den bu yana gövde değişmemiş. Gövde DÖNMEZ.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "* BAD_REQUEST — İstek biçimi hatalı: eksik alan, geçersiz değer ya da Idempotency-Key yok. Mesajı okuyup gövdeyi düzeltin; aynı istek tekrarlanırsa aynı hatayı alır.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Yetkisiz" }, "403": { "$ref": "#/components/responses/Yasak" }, "429": { "$ref": "#/components/responses/TavanAsimi" }, "500": { "$ref": "#/components/responses/IcHata" }, "503": { "$ref": "#/components/responses/Kapali" } } } }, "/catalog/products/{productId}": { "get": { "operationId": "product", "summary": "Tek ürün", "description": "Tek ürünün tam görünümü. Ürün başına zorunlu alan ŞEMASI burada yayınlanır: alan anahtarları (playerId, server, zoneId, character...) ürün başlıklarından türetilir. Bot bunları uydurmaz, buradan okur; sıra değil ANAHTAR ADI önemlidir.", "tags": [ "Katalog & fiyat" ], "x-oyuneks-scope": "catalog:read", "parameters": [ { "name": "productId", "in": "path", "required": true, "description": "Ürün kimliği (yalnız rakam).", "schema": { "type": "integer" }, "example": "1421" }, { "name": "If-None-Match", "in": "header", "required": false, "description": "Önceki yanıtın ETag değeri.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Başarılı", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "mode" ], "properties": { "data": { "$ref": "#/components/schemas/Product" }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "requestId": { "type": "string", "maxLength": 26 } } }, "example": { "data": { "productId": 1421, "name": "PUBG Mobile 660 UC", "type": "topup", "game": "pubg-mobile", "category": "pubg-mobile-uc", "region": null, "listPrice": "428.90", "price": "411.50", "currency": "TRY", "vatIncluded": true, "stock": { "mode": "instant" }, "limits": { "minQty": 1, "maxQty": 500 }, "requiredFields": [ { "key": "playerId", "label": "Oyuncu ID", "type": "string", "minLength": 8, "maxLength": 12, "required": true, "pattern": "^.{8,12}$", "placeholder": null } ], "delivery": { "mode": "instant", "etaSeconds": 30 }, "enabled": true, "updatedAt": null }, "mode": "live", "requestId": "01K3QF6ZC2M9V0X7NB4TDHR8YE" } } } }, "304": { "description": "Değişmedi: gönderdiğiniz ETag'den bu yana gövde değişmemiş. Gövde DÖNMEZ.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "* NOT_FOUND — Kayıt ya da uç bulunamadı. Kimliği ve adresi doğrulayın. Başka bayinin siparişi de \"bulunamadı\" döner (varlığını sızdırmayız).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Yetkisiz" }, "403": { "$ref": "#/components/responses/Yasak" }, "429": { "$ref": "#/components/responses/TavanAsimi" }, "500": { "$ref": "#/components/responses/IcHata" }, "503": { "$ref": "#/components/responses/Kapali" } } } }, "/catalog/prices": { "get": { "operationId": "prices", "summary": "Fiyat/stok dökümü ve delta", "description": "Ürün listesinin hafif sürümü: yalnız productId, fiyat, stok, satışta mı. Fiyat senkronu yapan botlar için. ?since verilirse GERÇEK DELTA döner (o tarihten sonra fiyatı/stoğu/durumu değişen ürünler, her satırda gerçek updatedAt). Anlık görüntü henüz oluşmamış bir hesapta süzgeç UYGULANMAZ: tam liste + uyarı notu döner, çünkü boş liste botun \"değişim yok\" sanıp fiyat senkronunu hiç yapmaması demek olurdu.", "tags": [ "Katalog & fiyat" ], "x-oyuneks-scope": "catalog:read", "parameters": [ { "name": "since", "in": "query", "required": false, "description": "Bu andan sonra değişen ürünler. Okunamayan değerde tam liste + note döner.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-08-28T09:00:00+03:00" }, { "name": "cursor", "in": "query", "required": false, "description": "Önceki yanıttaki nextCursor.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Sayfa boyu (1-200).", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 200 } }, { "name": "If-None-Match", "in": "header", "required": false, "description": "Önceki yanıtın ETag değeri.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Başarılı", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "mode" ], "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PriceRow" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Sonraki sayfa imleci; null ise sayfa bitti." }, "count": { "type": "integer" }, "note": { "type": "string", "description": "Süzgeç uygulanamadıysa nedeni." }, "asOf": { "type": "string", "format": "date-time" } } }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "requestId": { "type": "string", "maxLength": 26 } } }, "example": { "data": { "items": [ { "productId": 6, "listPrice": "105.00", "price": "96.20", "currency": "TRY", "stock": { "mode": "count", "count": 418 }, "enabled": true, "updatedAt": "2026-08-28T14:30:00+03:00" } ], "nextCursor": null, "count": 1, "asOf": "2026-08-28T14:35:00+03:00" }, "mode": "live", "requestId": "01K3QF6ZC2M9V0X7NB4TDHR8YE" } } } }, "304": { "description": "Değişmedi: gönderdiğiniz ETag'den bu yana gövde değişmemiş. Gövde DÖNMEZ.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Yetkisiz" }, "403": { "$ref": "#/components/responses/Yasak" }, "429": { "$ref": "#/components/responses/TavanAsimi" }, "500": { "$ref": "#/components/responses/IcHata" }, "503": { "$ref": "#/components/responses/Kapali" } } } }, "/orders/validate": { "post": { "operationId": "validate", "summary": "Oyuncu bilgisini önceden doğrula", "description": "Top-up ürünlerinde oyuncu bilgisini tedarikçiye ÖNCEDEN sorar; para düşmez. supported=false ise üründe önceden doğrulama yoktur (sipariş vermeyi engellemez). valid=null \"şu an kontrol edilemedi\" demektir: teknik hata satışı ENGELLEMEZ, aynı kontrol sipariş sırasında çekirdekte tekrar çalışır. Yanıtta requiredFields şeması da döner, böylece hangi alanları göndereceğinizi tek istekte öğrenirsiniz.", "tags": [ "Hesap doğrulama" ], "x-oyuneks-scope": "orders:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateRequest" }, "example": { "productId": 1421, "fields": { "playerId": "5123456789", "server": "7012" } } } } }, "responses": { "200": { "description": "Başarılı", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "mode" ], "properties": { "data": { "$ref": "#/components/schemas/ValidateResult" }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "requestId": { "type": "string", "maxLength": 26 } } }, "example": { "data": { "supported": true, "valid": true, "nickname": "OyuncuAdi", "validUntil": "2026-08-28T14:10:00+03:00", "requiredFields": [ { "key": "playerId", "label": "Oyuncu ID", "type": "string", "minLength": 8, "maxLength": 12, "validate": true } ], "message": null }, "mode": "live", "requestId": "01K3QF6ZC2M9V0X7NB4TDHR8YE" } } } }, "400": { "description": "* BAD_REQUEST — İstek biçimi hatalı: eksik alan, geçersiz değer ya da Idempotency-Key yok. Mesajı okuyup gövdeyi düzeltin; aynı istek tekrarlanırsa aynı hatayı alır.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "* NOT_FOUND — Kayıt ya da uç bulunamadı. Kimliği ve adresi doğrulayın. Başka bayinin siparişi de \"bulunamadı\" döner (varlığını sızdırmayız).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Yetkisiz" }, "403": { "$ref": "#/components/responses/Yasak" }, "429": { "$ref": "#/components/responses/TavanAsimi" }, "500": { "$ref": "#/components/responses/IcHata" }, "503": { "$ref": "#/components/responses/Kapali" } } } }, "/orders": { "post": { "operationId": "orderCreate", "summary": "Sipariş ver", "description": "Sipariş verir; tutar bakiyeden düşer. Idempotency-Key başlığı ZORUNLUDUR. Tek istekte en fazla 50 kalem. expectedPrice gönderilirse fiyat değişmişse sipariş VERİLMEZ (PRICE_CHANGED). waitForStock=false ise stok yetmiyorsa hiç başlamaz. Yanıt 201 (sonuç kesin) ya da 202 (teslimat sürüyor). Aynı anahtarla tekrar denerseniz aynı yanıt + Idempotent-Replayed: true başlığı döner, YENİ SİPARİŞ OLUŞMAZ; ağ koptuğunda tekrar göndermek güvenlidir.", "tags": [ "Sipariş" ], "x-oyuneks-scope": "orders:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Sizin benzersiz referansınız, en fazla 64 karakter. Her YENİ sipariş için yeni anahtar üretin. Anahtar 24 saat hatırlanır.", "schema": { "type": "string", "maxLength": 64 }, "example": "SIP-2026-0001-1" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCreateRequest" }, "example": { "externalRef": "SIP-2026-0001", "waitForStock": true, "items": [ { "productId": 6, "quantity": 2, "expectedPrice": "98.70" }, { "productId": 1421, "quantity": 1, "fields": { "playerId": "5123456789" } } ] } } } }, "responses": { "201": { "description": "Başarılı", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "mode" ], "properties": { "data": { "$ref": "#/components/schemas/Order" }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "requestId": { "type": "string", "maxLength": 26 } } }, "example": { "data": { "orderId": 184213, "externalRef": "SIP-2026-0001", "channel": "dealer-api", "status": "delivered", "mode": "live", "total": "608.90", "balanceAfter": "47641.10", "createdAt": "2026-08-28T14:05:00+03:00", "items": [ { "itemId": "184213-1", "productId": 6, "name": "Knight Online 1020 Cash", "quantity": 2, "unitPrice": "98.70", "status": "delivered", "codes": [ { "code": "KO10-2XQ4-9WPA", "serial": null, "expiresAt": null }, { "code": "KO10-7MTB-3VZC", "serial": null, "expiresAt": null } ], "receipt": null, "failCode": null, "failReason": null }, { "itemId": "184213-2", "productId": 1421, "name": "PUBG Mobile 660 UC", "quantity": 1, "unitPrice": "411.50", "status": "delivered", "codes": [], "receipt": "TOPUP-9F31A2", "failCode": null, "failReason": null } ] }, "mode": "live", "requestId": "01K3QF6ZC2M9V0X7NB4TDHR8YE" } } } }, "202": { "description": "En az bir kalem stok bekliyor ya da tedarikçiden çekiliyor (status=processing). Sonucu webhook ile ya da GET /orders/{orderId} ile öğrenin.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "mode" ], "properties": { "data": { "$ref": "#/components/schemas/Order" }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "requestId": { "type": "string", "maxLength": 26 } } } } } }, "400": { "description": "* BAD_REQUEST — İstek biçimi hatalı: eksik alan, geçersiz değer ya da Idempotency-Key yok. Mesajı okuyup gövdeyi düzeltin; aynı istek tekrarlanırsa aynı hatayı alır.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "* IDEMPOTENCY_MISMATCH — Aynı Idempotency-Key daha önce FARKLI bir gövdeyle kullanıldı. Her yeni sipariş için yeni anahtar üretin (kendi sipariş numaranız + deneme sayacı iyi bir kalıp).\n* ORDER_IN_PROGRESS — Aynı anahtarla bir sipariş şu an işleniyor. Birkaç saniye bekleyip GET /orders/by-ref/{externalRef} ile sonucu okuyun.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "* INSUFFICIENT_BALANCE — Bakiye yetersiz. details.required ve details.available tutarları yanıtta döner. Bakiye yükleyip tekrar deneyin.\n* PRICE_CHANGED — Gönderdiğiniz expectedPrice güncel fiyattan farklı; sipariş VERİLMEDİ. details.current güncel fiyatı taşır. Kataloğu tazeleyip yeni fiyatla tekrar deneyin.\n* OUT_OF_STOCK — Stok yetersiz (waitForStock=false gönderildi). Bir süre sonra tekrar deneyin ya da waitForStock=true ile kuyruğa alın.\n* INVALID_FIELDS — Zorunlu alanlar eksik ya da uzunluk kısıtına uymuyor. details.fields hatalı alanları listeler. Şemayı GET /catalog/products/{productId} ucundan okuyun.\n* INVALID_PLAYER_ID — Oyuncu bilgisi tedarikçi tarafında doğrulanamadı. Sipariş öncesi POST /orders/validate ile kontrol edin; müşteriden doğru kimliği isteyin.\n* LIMIT_EXCEEDED — Günlük sipariş limiti ya da kalem başına adet tavanı aşıldı. GET /me ucundaki limits alanına bakın; günlük limit gece sıfırlanır.\n* PRODUCT_DISABLED — Ürün satışta değil ya da fiyatı tanımlı değil. Kataloğu tazeleyin; ürün geri açıldığında product.enabled olayı gelir.\n* PRODUCT_NOT_ALLOWED — Ürün bayi kanalından satılamaz. Bu ürünler katalog uçlarında da listelenmez; sipariş gövdesinden çıkarın.\n* MIN_QTY — Ürünün asgari sipariş adedinin altında kalındı. Katalogdaki limits.minQty değerini kullanın.\n* PRODUCT_NOT_ALLOWED — Ürün bayi kanalından satılamaz. Bu ürünler katalog uçlarında da listelenmez; sipariş gövdesinden çıkarın.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Yetkisiz" }, "403": { "$ref": "#/components/responses/Yasak" }, "429": { "$ref": "#/components/responses/TavanAsimi" }, "500": { "$ref": "#/components/responses/IcHata" }, "503": { "$ref": "#/components/responses/Kapali" } } }, "get": { "operationId": "orderList", "summary": "Sipariş listesi (imleçli)", "description": "Bayinin siparişleri; panel ve API siparişleri aynı listede (ikisi aynı caridir), channel ile ayrılabilir. productId süzgeci YALNIZ DÖNEN SAYFAYA uygulanır: sipariş içeriği JSON anlık görüntü içinde durduğu için SQL ile aranamaz. Bu durumda yanıtta note alanı çıkar; bot \"ürün yok\" sanmasın diye susmuyoruz.", "tags": [ "Sipariş" ], "x-oyuneks-scope": "orders:read", "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Başlangıç tarihi (dahil).", "schema": { "type": "string", "format": "date" }, "example": "2026-08-01" }, { "name": "to", "in": "query", "required": false, "description": "Bitiş tarihi (dahil).", "schema": { "type": "string", "format": "date" }, "example": "2026-08-28" }, { "name": "status", "in": "query", "required": false, "description": "Durum süzgeci. Geçersiz değer 400 döner (sessizce yok sayılmaz).", "schema": { "type": "string", "enum": [ "processing", "delivered", "partially_delivered", "cancelled", "failed" ] } }, { "name": "channel", "in": "query", "required": false, "description": "Kanal süzgeci. Boş bırakılırsa iki kanal birlikte döner.", "schema": { "type": "string", "enum": [ "dealer-api", "dealer-panel" ] } }, { "name": "productId", "in": "query", "required": false, "description": "Yalnız dönen sayfa içinde süzer; sonraki sayfalar için nextCursor ile devam edin.", "schema": { "type": "integer" }, "example": "6" }, { "name": "cursor", "in": "query", "required": false, "description": "Önceki yanıttaki nextCursor (son sipariş numarası).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Sayfa boyu (1-100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Başarılı", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "mode" ], "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Sonraki sayfa imleci; null ise sayfa bitti." }, "count": { "type": "integer" }, "note": { "type": "string", "description": "Süzgeç uygulanamadıysa nedeni." } } }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "requestId": { "type": "string", "maxLength": 26 } } }, "example": { "data": { "items": [ { "orderId": 184213, "externalRef": "SIP-2026-0001", "channel": "dealer-api", "status": "delivered", "mode": "live", "total": "608.90", "balanceAfter": "47641.10", "createdAt": "2026-08-28T14:05:00+03:00", "items": [ { "itemId": "184213-1", "productId": 6, "name": "Knight Online 1020 Cash", "quantity": 2, "unitPrice": "98.70", "status": "delivered", "codes": [], "receipt": null, "failCode": null, "failReason": null } ] } ], "nextCursor": "184213", "count": 1 }, "mode": "live", "requestId": "01K3QF6ZC2M9V0X7NB4TDHR8YE" } } } }, "400": { "description": "* BAD_REQUEST — İstek biçimi hatalı: eksik alan, geçersiz değer ya da Idempotency-Key yok. Mesajı okuyup gövdeyi düzeltin; aynı istek tekrarlanırsa aynı hatayı alır.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Yetkisiz" }, "403": { "$ref": "#/components/responses/Yasak" }, "429": { "$ref": "#/components/responses/TavanAsimi" }, "500": { "$ref": "#/components/responses/IcHata" }, "503": { "$ref": "#/components/responses/Kapali" } } } }, "/orders/{orderId}": { "get": { "operationId": "orderShow", "summary": "Sipariş detayı ve kodlar", "description": "Sipariş detayı + teslim edilen kodlar. Kodlar YALNIZ bu uçta ve sipariş yanıtında döner; webhook gövdesinde asla gönderilmez. Test modunda verilen siparişlerin kimliği \"test_12\" biçimindedir ve aynı uçtan okunur. Başka bayinin siparişi 404 döner.", "tags": [ "Sipariş" ], "x-oyuneks-scope": "orders:read", "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "Sipariş numarası ya da test siparişi kimliği (test_12).", "schema": { "type": "string", "pattern": "[0-9]+|test_[0-9]+" }, "example": "184213" } ], "responses": { "200": { "description": "Başarılı", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "mode" ], "properties": { "data": { "$ref": "#/components/schemas/Order" }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "requestId": { "type": "string", "maxLength": 26 } } }, "example": { "data": { "orderId": 184213, "externalRef": "SIP-2026-0001", "channel": "dealer-api", "status": "partially_delivered", "mode": "live", "total": "608.90", "balanceAfter": "47641.10", "createdAt": "2026-08-28T14:05:00+03:00", "items": [ { "itemId": "184213-1", "productId": 6, "name": "Knight Online 1020 Cash", "quantity": 2, "unitPrice": "98.70", "status": "delivered", "codes": [ { "code": "KO10-2XQ4-9WPA", "serial": null, "expiresAt": null } ], "receipt": null, "failCode": null, "failReason": null }, { "itemId": "184213-2", "productId": 1421, "name": "PUBG Mobile 660 UC", "quantity": 1, "unitPrice": "411.50", "status": "failed", "codes": [], "receipt": null, "failCode": "TIMEOUT", "failReason": "ZAMAN_ASIMI: stok 15 dk icinde saglanamadi" } ] }, "mode": "live", "requestId": "01K3QF6ZC2M9V0X7NB4TDHR8YE" } } } }, "404": { "description": "* NOT_FOUND — Kayıt ya da uç bulunamadı. Kimliği ve adresi doğrulayın. Başka bayinin siparişi de \"bulunamadı\" döner (varlığını sızdırmayız).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Yetkisiz" }, "403": { "$ref": "#/components/responses/Yasak" }, "429": { "$ref": "#/components/responses/TavanAsimi" }, "500": { "$ref": "#/components/responses/IcHata" }, "503": { "$ref": "#/components/responses/Kapali" } } } }, "/orders/by-ref/{externalRef}": { "get": { "operationId": "orderByRef", "summary": "Kendi referansınızla sipariş bul", "description": "Bayinin kendi referansıyla sipariş bulur (aynı referansla birden fazla kayıt varsa EN SON kayıt). Ağ hatasından sonra \"sipariş düştü mü\" sorusunun en hızlı yanıtı budur. Test siparişleri de bu uçtan bulunur.", "tags": [ "Sipariş" ], "x-oyuneks-scope": "orders:read", "parameters": [ { "name": "externalRef", "in": "path", "required": true, "description": "Sipariş gövdesinde gönderdiğiniz externalRef (1-64 karakter, / içeremez).", "schema": { "type": "string", "maxLength": 64 }, "example": "SIP-2026-0001" } ], "responses": { "200": { "description": "Başarılı", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "mode" ], "properties": { "data": { "$ref": "#/components/schemas/Order" }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "requestId": { "type": "string", "maxLength": 26 } } }, "example": { "data": { "orderId": 184213, "externalRef": "SIP-2026-0001", "channel": "dealer-api", "status": "delivered", "mode": "live", "total": "608.90", "balanceAfter": "47641.10", "createdAt": "2026-08-28T14:05:00+03:00", "items": [] }, "mode": "live", "requestId": "01K3QF6ZC2M9V0X7NB4TDHR8YE" } } } }, "404": { "description": "* NOT_FOUND — Kayıt ya da uç bulunamadı. Kimliği ve adresi doğrulayın. Başka bayinin siparişi de \"bulunamadı\" döner (varlığını sızdırmayız).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Yetkisiz" }, "403": { "$ref": "#/components/responses/Yasak" }, "429": { "$ref": "#/components/responses/TavanAsimi" }, "500": { "$ref": "#/components/responses/IcHata" }, "503": { "$ref": "#/components/responses/Kapali" } } } }, "/orders/{orderId}/cancel": { "post": { "operationId": "orderCancel", "summary": "Bekleyen kalemleri iptal et", "description": "Yalnız BEKLEYEN (processing) kalemleri iptal eder ve tutarı iade alır. Teslim edilmiş kaleme dokunulmaz: kod sizde, kullanılmamış kod iadesi destek kararıdır. İade ve muhasebe işini kanonik teslimat yolu yapar, bu uç ayrı bir iade yolu açmaz. GB (oyun parası) kalemi bu uçtan iptal EDİLEMEZ (NOT_CANCELLABLE): teslimat elle yapıldığı için iade de elle yapılır, destek ekibine yazın.", "tags": [ "Sipariş" ], "x-oyuneks-scope": "orders:write", "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "Sipariş numarası (yalnız rakam; test siparişi iptal edilmez).", "schema": { "type": "integer" }, "example": "184219" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCancelRequest" }, "example": { "reason": "Müşteri vazgeçti" } } } }, "responses": { "200": { "description": "Başarılı", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "mode" ], "properties": { "data": { "$ref": "#/components/schemas/Order" }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "requestId": { "type": "string", "maxLength": 26 } } }, "example": { "data": { "orderId": 184219, "externalRef": "SIP-2026-0007", "channel": "dealer-api", "status": "cancelled", "mode": "live", "total": "41.90", "balanceAfter": "48250.00", "createdAt": "2026-08-28T14:20:00+03:00", "items": [ { "itemId": "184219-1", "productId": 1421, "name": "PUBG Mobile 660 UC", "quantity": 1, "unitPrice": "41.90", "status": "cancelled", "codes": [], "receipt": null, "failCode": "CANCELLED", "failReason": "Müşteri vazgeçti" } ] }, "mode": "live", "requestId": "01K3QF6ZC2M9V0X7NB4TDHR8YE" } } } }, "400": { "description": "* BAD_REQUEST — İstek biçimi hatalı: eksik alan, geçersiz değer ya da Idempotency-Key yok. Mesajı okuyup gövdeyi düzeltin; aynı istek tekrarlanırsa aynı hatayı alır.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "* NOT_FOUND — Kayıt ya da uç bulunamadı. Kimliği ve adresi doğrulayın. Başka bayinin siparişi de \"bulunamadı\" döner (varlığını sızdırmayız).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "* NOT_CANCELLABLE — GB (oyun parası) kalemi bu uçtan iptal edilemez; teslimat elle yapılır. İptal için destek ekibine yazın. Aynı siparişteki e-pin/top-up kalemleri normal şekilde iptal edilir.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Yetkisiz" }, "403": { "$ref": "#/components/responses/Yasak" }, "429": { "$ref": "#/components/responses/TavanAsimi" }, "500": { "$ref": "#/components/responses/IcHata" }, "503": { "$ref": "#/components/responses/Kapali" } } } }, "/reports/statement": { "get": { "operationId": "statement", "summary": "Dönem ekstresi (json/csv)", "description": "Açılış bakiyesi, yükleme/sipariş/iade toplamları, kapanış bakiyesi ve hareket satırları. format=csv doğrudan muhasebe programına verilebilecek dosya döner (BOM ile, noktalı virgül ayırıcı, zarf YOK). Dönemde 5000 satır tavanına ulaşılırsa yanıtta note çıkar; aralığı daraltın.", "tags": [ "Raporlar" ], "x-oyuneks-scope": "balance:read", "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Başlangıç tarihi. Boşsa içinde bulunulan ayın 1'i.", "schema": { "type": "string", "format": "date", "default": "ayın 1'i" }, "example": "2026-08-01" }, { "name": "to", "in": "query", "required": false, "description": "Bitiş tarihi. from > to ise 400 döner.", "schema": { "type": "string", "format": "date", "default": "bugün" }, "example": "2026-08-28" }, { "name": "format", "in": "query", "required": false, "description": "csv seçilirse dosya indirmesi döner (text/csv).", "schema": { "type": "string", "enum": [ "json", "csv" ], "default": "json" } } ], "responses": { "200": { "description": "Başarılı", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "mode" ], "properties": { "data": { "$ref": "#/components/schemas/Statement" }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "requestId": { "type": "string", "maxLength": 26 } } }, "example": { "data": { "from": "2026-08-01", "to": "2026-08-28", "currency": "TRY", "openingBalance": "12500.00", "deposits": "75000.00", "orders": "39250.00", "refunds": "0.00", "other": "0.00", "closingBalance": "48250.00", "count": 2, "items": [ { "id": 3012301, "date": "2026-08-28T09:12:00+03:00", "typeId": 2, "amount": "25000.00", "balanceAfter": "48250.00", "orderId": null, "description": "Havale" }, { "id": 3012402, "date": "2026-08-28T14:05:00+03:00", "typeId": 1, "amount": "-608.90", "balanceAfter": "47641.10", "orderId": 184213, "description": "Sipariş ödemesi" } ] }, "mode": "live", "requestId": "01K3QF6ZC2M9V0X7NB4TDHR8YE" } } } }, "400": { "description": "* BAD_REQUEST — İstek biçimi hatalı: eksik alan, geçersiz değer ya da Idempotency-Key yok. Mesajı okuyup gövdeyi düzeltin; aynı istek tekrarlanırsa aynı hatayı alır.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Yetkisiz" }, "403": { "$ref": "#/components/responses/Yasak" }, "429": { "$ref": "#/components/responses/TavanAsimi" }, "500": { "$ref": "#/components/responses/IcHata" }, "503": { "$ref": "#/components/responses/Kapali" } } } }, "/invoices": { "get": { "operationId": "invoices", "summary": "Fatura listesi", "description": "Kesilen faturalar: numara, tarih, tutar, KDV ve panel adresi. PDF/UBL indirme bağlantısı henüz API üzerinden VERİLMİYOR (pdfUrl null): sitedeki fatura görüntüleme ucu oturumlu, imzalı ve süresi kısıtlı bir indirme bağlantısı üretmek yeni bir yetkilendirme yüzeyi açmak demek ve bu sürümün kapsamında değil. Belge panelUrl adresinden görüntülenir.", "tags": [ "Raporlar" ], "x-oyuneks-scope": "balance:read", "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Başlangıç tarihi (dahil).", "schema": { "type": "string", "format": "date" }, "example": "2026-08-01" }, { "name": "to", "in": "query", "required": false, "description": "Bitiş tarihi (dahil).", "schema": { "type": "string", "format": "date" }, "example": "2026-08-28" } ], "responses": { "200": { "description": "Başarılı", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "mode" ], "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Sonraki sayfa imleci; null ise sayfa bitti." }, "count": { "type": "integer" }, "note": { "type": "string", "description": "Süzgeç uygulanamadıysa nedeni." } } }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "requestId": { "type": "string", "maxLength": 26 } } }, "example": { "data": { "items": [ { "invoiceId": 90124, "number": "OYN2026000012345", "numbers": [ "OYN2026000012345" ], "date": "2026-08-01T10:00:00+03:00", "type": "satis", "orderNo": "184213", "total": "608.90", "vat": "0.00", "currency": "TRY", "pdfUrl": null, "panelUrl": "/faturalarim/90124" } ], "count": 1, "note": "PDF indirme baglantisi henuz API uzerinden verilmiyor; belge panelUrl adresinden (oturumlu) goruntulenir." }, "mode": "live", "requestId": "01K3QF6ZC2M9V0X7NB4TDHR8YE" } } } }, "401": { "$ref": "#/components/responses/Yetkisiz" }, "403": { "$ref": "#/components/responses/Yasak" }, "429": { "$ref": "#/components/responses/TavanAsimi" }, "500": { "$ref": "#/components/responses/IcHata" }, "503": { "$ref": "#/components/responses/Kapali" } } } }, "/webhooks": { "get": { "operationId": "webhookGet", "summary": "Abonelik durumu", "description": "Adres, abone olunan olaylar, durum (active|suspended), son başarı/hata damgası, üst üste hata sayacı ve MASKELENMİŞ imza sırrı. Ham sır BU UÇTA DÖNMEZ: jetonu okuyabilen biri sırrı da okuyabilseydi imzanın anlamı kalmazdı. Yanıtta abone olunabilecek olayların katalogu da döner.", "tags": [ "Webhook'lar" ], "x-oyuneks-scope": "webhooks:manage", "responses": { "200": { "description": "Başarılı", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "mode" ], "properties": { "data": { "type": "object", "properties": { "configured": { "type": "boolean" }, "webhook": { "anyOf": [ { "$ref": "#/components/schemas/WebhookSubscription" }, { "type": "null" } ] }, "availableEvents": { "type": "object", "additionalProperties": { "type": "string" } } } }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "requestId": { "type": "string", "maxLength": 26 } } }, "example": { "data": { "configured": true, "webhook": { "id": 214, "url": "https://bayi.example.com/oyuneks-hook", "events": [ "order.delivered", "order.failed", "price.changed", "balance.low" ], "status": "active", "secretMasked": "whsec_a91f3c********9d0e", "failStreak": 0, "lastSuccessAt": "2026-08-28T14:05:00+03:00", "lastFailureAt": null }, "availableEvents": { "order.delivered": "Siparis teslim edildi (kismi teslim de bu olayla gelir)" } }, "mode": "live", "requestId": "01K3QF6ZC2M9V0X7NB4TDHR8YE" } } } }, "401": { "$ref": "#/components/responses/Yetkisiz" }, "403": { "$ref": "#/components/responses/Yasak" }, "429": { "$ref": "#/components/responses/TavanAsimi" }, "500": { "$ref": "#/components/responses/IcHata" }, "503": { "$ref": "#/components/responses/Kapali" } } }, "put": { "operationId": "webhookSave", "summary": "Aboneliği oluştur/güncelle", "description": "Bayi başına TEK adres olduğu için bu bir \"upsert\"tir. Adres yalnız https olabilir; localhost ve özel ağ adresleri reddedilir (SSRF). İLK KAYITTA imza sırrı yanıtta BİR KEZ döner, bir daha gösterilmez. Adres değiştirilirse askı (varsa) kalkar. Bilinmeyen olay adı sessizce düşürülmez, 400 ile söylenir: yoksa bot \"abone oldum\" sanıp olayı beklerdi. events boş gönderilirse varsayılan set uygulanır. POST /webhooks aynı işe bağlıdır.", "tags": [ "Webhook'lar" ], "x-oyuneks-scope": "webhooks:manage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSaveRequest" }, "example": { "url": "https://bayi.example.com/oyuneks-hook", "events": [ "order.delivered", "order.failed", "price.changed", "balance.low" ] } } } }, "responses": { "200": { "description": "Başarılı", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "mode" ], "properties": { "data": { "type": "object", "properties": { "webhook": { "$ref": "#/components/schemas/WebhookSubscription" }, "signature": { "$ref": "#/components/schemas/WebhookSignatureInfo" }, "secret": { "type": "string", "description": "Yalnız üretim anında döner (whsec_...)." }, "secretNote": { "type": "string" } } }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "requestId": { "type": "string", "maxLength": 26 } } }, "example": { "data": { "webhook": { "id": 214, "url": "https://bayi.example.com/oyuneks-hook", "events": [ "order.delivered", "order.failed", "price.changed", "balance.low" ], "status": "active", "secretMasked": "whsec_a91f3c********9d0e", "failStreak": 0, "lastSuccessAt": null, "lastFailureAt": null }, "signature": { "header": "X-Oyuneks-Signature", "format": "t=,v1=", "algorithm": "HMAC-SHA256" }, "secret": "whsec_a91f3c7d2b8e4f16a05c9d0e", "secretNote": "Bu sir yalniz bu yanitta doner." }, "mode": "live", "requestId": "01K3QF6ZC2M9V0X7NB4TDHR8YE" } } } }, "400": { "description": "* BAD_REQUEST — İstek biçimi hatalı: eksik alan, geçersiz değer ya da Idempotency-Key yok. Mesajı okuyup gövdeyi düzeltin; aynı istek tekrarlanırsa aynı hatayı alır.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Yetkisiz" }, "403": { "$ref": "#/components/responses/Yasak" }, "429": { "$ref": "#/components/responses/TavanAsimi" }, "500": { "$ref": "#/components/responses/IcHata" }, "503": { "$ref": "#/components/responses/Kapali" } } }, "post": { "operationId": "webhookSaveAliasPost", "summary": "Aboneliği oluştur/güncelle (eş adres)", "description": "F3'te ilan edilen adresle uyum için korunan eş adres; şu uçla aynı işi yapar: PUT /bayi-api/v1/webhooks.\n\nBayi başına TEK adres olduğu için bu bir \"upsert\"tir. Adres yalnız https olabilir; localhost ve özel ağ adresleri reddedilir (SSRF). İLK KAYITTA imza sırrı yanıtta BİR KEZ döner, bir daha gösterilmez. Adres değiştirilirse askı (varsa) kalkar. Bilinmeyen olay adı sessizce düşürülmez, 400 ile söylenir: yoksa bot \"abone oldum\" sanıp olayı beklerdi. events boş gönderilirse varsayılan set uygulanır. POST /webhooks aynı işe bağlıdır.", "tags": [ "Webhook'lar" ], "x-oyuneks-scope": "webhooks:manage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSaveRequest" }, "example": { "url": "https://bayi.example.com/oyuneks-hook", "events": [ "order.delivered", "order.failed", "price.changed", "balance.low" ] } } } }, "responses": { "200": { "description": "Başarılı", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "mode" ], "properties": { "data": { "type": "object", "properties": { "webhook": { "$ref": "#/components/schemas/WebhookSubscription" }, "signature": { "$ref": "#/components/schemas/WebhookSignatureInfo" }, "secret": { "type": "string", "description": "Yalnız üretim anında döner (whsec_...)." }, "secretNote": { "type": "string" } } }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "requestId": { "type": "string", "maxLength": 26 } } }, "example": { "data": { "webhook": { "id": 214, "url": "https://bayi.example.com/oyuneks-hook", "events": [ "order.delivered", "order.failed", "price.changed", "balance.low" ], "status": "active", "secretMasked": "whsec_a91f3c********9d0e", "failStreak": 0, "lastSuccessAt": null, "lastFailureAt": null }, "signature": { "header": "X-Oyuneks-Signature", "format": "t=,v1=", "algorithm": "HMAC-SHA256" }, "secret": "whsec_a91f3c7d2b8e4f16a05c9d0e", "secretNote": "Bu sir yalniz bu yanitta doner." }, "mode": "live", "requestId": "01K3QF6ZC2M9V0X7NB4TDHR8YE" } } } }, "400": { "description": "* BAD_REQUEST — İstek biçimi hatalı: eksik alan, geçersiz değer ya da Idempotency-Key yok. Mesajı okuyup gövdeyi düzeltin; aynı istek tekrarlanırsa aynı hatayı alır.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Yetkisiz" }, "403": { "$ref": "#/components/responses/Yasak" }, "429": { "$ref": "#/components/responses/TavanAsimi" }, "500": { "$ref": "#/components/responses/IcHata" }, "503": { "$ref": "#/components/responses/Kapali" } } }, "delete": { "operationId": "webhookDelete", "summary": "Aboneliği sil", "description": "Aboneliği siler; kuyrukta bekleyen olaylar ölü işaretlenir. DELETE /webhooks/{webhookId} de kabul edilir; kimlik başka bayiye aitse 404 döner (varlığını sızdırmayız). Silmek yerine olay listesini daraltmak genelde daha iyidir: adres silindiğinde teslim bildirimlerini de kaybedersiniz.", "tags": [ "Webhook'lar" ], "x-oyuneks-scope": "webhooks:manage", "responses": { "200": { "description": "Başarılı", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "mode" ], "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "requestId": { "type": "string", "maxLength": 26 } } }, "example": { "data": { "deleted": true }, "mode": "live", "requestId": "01K3QF6ZC2M9V0X7NB4TDHR8YE" } } } }, "404": { "description": "* NOT_FOUND — Kayıt ya da uç bulunamadı. Kimliği ve adresi doğrulayın. Başka bayinin siparişi de \"bulunamadı\" döner (varlığını sızdırmayız).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Yetkisiz" }, "403": { "$ref": "#/components/responses/Yasak" }, "429": { "$ref": "#/components/responses/TavanAsimi" }, "500": { "$ref": "#/components/responses/IcHata" }, "503": { "$ref": "#/components/responses/Kapali" } } } }, "/webhooks/deliveries": { "get": { "operationId": "webhookDeliveries", "summary": "Gönderim kaydı (imleçli)", "description": "Olay adı, kanal (webhook|email), durum (pending|sent|dead), deneme sayısı, HTTP kodu, süre ve hata metni. Olay GÖVDESİ döndürülmez; gövdeyi ikinci bir yerden yayınlamak gereksiz yüzey olurdu. Yeniden gönderim şu an yalnız Bayi Panelinden yapılır. Yanıtta yeniden deneme tablosu da döner.", "tags": [ "Webhook'lar" ], "x-oyuneks-scope": "webhooks:manage", "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Önceki yanıttaki nextCursor.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Sayfa boyu (1-200).", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "Başarılı", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "mode" ], "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Sonraki sayfa imleci; null ise sayfa bitti." }, "count": { "type": "integer" }, "note": { "type": "string", "description": "Süzgeç uygulanamadıysa nedeni." }, "retry": { "$ref": "#/components/schemas/WebhookRetryPolicy" } } }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "requestId": { "type": "string", "maxLength": 26 } } }, "example": { "data": { "items": [ { "id": 9214, "eventId": "evt_o184213_d", "type": "order.delivered", "channel": "webhook", "mode": "live", "status": "sent", "attempts": 1, "httpCode": 200, "durationMs": 184, "error": null, "createdAt": "2026-08-28T14:05:01+03:00", "nextAttemptAt": null, "sentAt": "2026-08-28T14:05:02+03:00" } ], "nextCursor": "9214", "count": 1, "retry": { "maxAttempts": 8, "backoffMinutes": [ 2, 4, 8, 16, 32, 64, 128 ], "note": "Tavan 720 dakikadir. 8 denemede cevap alinamazsa olay olu sayilir." } }, "mode": "live", "requestId": "01K3QF6ZC2M9V0X7NB4TDHR8YE" } } } }, "401": { "$ref": "#/components/responses/Yetkisiz" }, "403": { "$ref": "#/components/responses/Yasak" }, "429": { "$ref": "#/components/responses/TavanAsimi" }, "500": { "$ref": "#/components/responses/IcHata" }, "503": { "$ref": "#/components/responses/Kapali" } } } }, "/webhooks/rotate-secret": { "post": { "operationId": "webhookRotate", "summary": "İmza sırrını yenile", "description": "Yeni imza sırrı üretir ve BİR KEZ döndürür. Eski sır ANINDA geçersizdir: iki geçerli sır tutmak, sızan sırrı iptal etmeyi anlamsız kılardı. Yeni sırrı yazana kadar gelen olayların imzası doğrulanamaz, bu yüzden dağıtımı hemen yapın.", "tags": [ "Webhook'lar" ], "x-oyuneks-scope": "webhooks:manage", "responses": { "200": { "description": "Başarılı", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "mode" ], "properties": { "data": { "type": "object", "properties": { "webhook": { "$ref": "#/components/schemas/WebhookSubscription" }, "signature": { "$ref": "#/components/schemas/WebhookSignatureInfo" }, "secret": { "type": "string", "description": "Yalnız üretim anında döner (whsec_...)." }, "secretNote": { "type": "string" } } }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "requestId": { "type": "string", "maxLength": 26 } } }, "example": { "data": { "secret": "whsec_2f7c81a94de0b3c65a1f8d42", "secretNote": "Eski sir ANINDA gecersizdir.", "webhook": { "id": 214, "url": "https://bayi.example.com/oyuneks-hook", "events": [ "order.delivered" ], "status": "active", "secretMasked": "whsec_2f7c81********8d42" }, "signature": { "header": "X-Oyuneks-Signature", "format": "t=,v1=", "algorithm": "HMAC-SHA256" } }, "mode": "live", "requestId": "01K3QF6ZC2M9V0X7NB4TDHR8YE" } } } }, "400": { "description": "* BAD_REQUEST — İstek biçimi hatalı: eksik alan, geçersiz değer ya da Idempotency-Key yok. Mesajı okuyup gövdeyi düzeltin; aynı istek tekrarlanırsa aynı hatayı alır.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Yetkisiz" }, "403": { "$ref": "#/components/responses/Yasak" }, "429": { "$ref": "#/components/responses/TavanAsimi" }, "500": { "$ref": "#/components/responses/IcHata" }, "503": { "$ref": "#/components/responses/Kapali" } } } }, "/webhooks/test": { "post": { "operationId": "webhookTest", "summary": "Test olayı gönder (ping)", "description": "\"ping\" olayını ANINDA gönderir (kuyruğa girmez, yeniden denenmez) ve HTTP sonucunu döndürür. Adres cevap vermezse yanıt YİNE 200 olur, gövdedeki delivered=false bakılır: istek doğru işlendi, gönderim başarısız. 502 döndürmek botu \"benim isteğim hatalı\" sanmaya iterdi. POST /webhooks/{webhookId}/test aynı işe bağlıdır.", "tags": [ "Webhook'lar" ], "x-oyuneks-scope": "webhooks:manage", "responses": { "200": { "description": "Başarılı", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "mode" ], "properties": { "data": { "type": "object", "required": [ "delivered" ], "properties": { "delivered": { "type": "boolean", "description": "false: istek işlendi ama gönderim başarısız." }, "eventId": { "type": [ "string", "null" ] }, "httpCode": { "type": [ "integer", "null" ] }, "durationMs": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] } } }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "requestId": { "type": "string", "maxLength": 26 } } }, "example": { "data": { "delivered": true, "eventId": "evt_01K3QF6ZC2M9V0X7NB4TDHR8YE", "httpCode": 200, "durationMs": 184, "error": null }, "mode": "test", "requestId": "01K3QF6ZC2M9V0X7NB4TDHR8YE" } } } }, "400": { "description": "* BAD_REQUEST — İstek biçimi hatalı: eksik alan, geçersiz değer ya da Idempotency-Key yok. Mesajı okuyup gövdeyi düzeltin; aynı istek tekrarlanırsa aynı hatayı alır.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Yetkisiz" }, "403": { "$ref": "#/components/responses/Yasak" }, "429": { "$ref": "#/components/responses/TavanAsimi" }, "500": { "$ref": "#/components/responses/IcHata" }, "503": { "$ref": "#/components/responses/Kapali" } } } }, "/webhooks/{webhookId}/test": { "post": { "operationId": "webhookTestAliasPost", "summary": "Test olayı gönder (ping) (eş adres)", "description": "F3'te ilan edilen adresle uyum için korunan eş adres; şu uçla aynı işi yapar: POST /bayi-api/v1/webhooks/test.\n\n\"ping\" olayını ANINDA gönderir (kuyruğa girmez, yeniden denenmez) ve HTTP sonucunu döndürür. Adres cevap vermezse yanıt YİNE 200 olur, gövdedeki delivered=false bakılır: istek doğru işlendi, gönderim başarısız. 502 döndürmek botu \"benim isteğim hatalı\" sanmaya iterdi. POST /webhooks/{webhookId}/test aynı işe bağlıdır.", "tags": [ "Webhook'lar" ], "x-oyuneks-scope": "webhooks:manage", "parameters": [ { "name": "webhookId", "in": "path", "required": true, "description": "GET /webhooks yanıtındaki abonelik kimliği. Başka bayiye aitse 404 döner.", "schema": { "type": "integer" }, "example": "214" } ], "responses": { "200": { "description": "Başarılı", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "mode" ], "properties": { "data": { "type": "object", "required": [ "delivered" ], "properties": { "delivered": { "type": "boolean", "description": "false: istek işlendi ama gönderim başarısız." }, "eventId": { "type": [ "string", "null" ] }, "httpCode": { "type": [ "integer", "null" ] }, "durationMs": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] } } }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "requestId": { "type": "string", "maxLength": 26 } } }, "example": { "data": { "delivered": true, "eventId": "evt_01K3QF6ZC2M9V0X7NB4TDHR8YE", "httpCode": 200, "durationMs": 184, "error": null }, "mode": "test", "requestId": "01K3QF6ZC2M9V0X7NB4TDHR8YE" } } } }, "400": { "description": "* BAD_REQUEST — İstek biçimi hatalı: eksik alan, geçersiz değer ya da Idempotency-Key yok. Mesajı okuyup gövdeyi düzeltin; aynı istek tekrarlanırsa aynı hatayı alır.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Yetkisiz" }, "403": { "$ref": "#/components/responses/Yasak" }, "429": { "$ref": "#/components/responses/TavanAsimi" }, "500": { "$ref": "#/components/responses/IcHata" }, "503": { "$ref": "#/components/responses/Kapali" } } } }, "/webhooks/{webhookId}": { "delete": { "operationId": "webhookDeleteAliasDelete", "summary": "Aboneliği sil (eş adres)", "description": "F3'te ilan edilen adresle uyum için korunan eş adres; şu uçla aynı işi yapar: DELETE /bayi-api/v1/webhooks.\n\nAboneliği siler; kuyrukta bekleyen olaylar ölü işaretlenir. DELETE /webhooks/{webhookId} de kabul edilir; kimlik başka bayiye aitse 404 döner (varlığını sızdırmayız). Silmek yerine olay listesini daraltmak genelde daha iyidir: adres silindiğinde teslim bildirimlerini de kaybedersiniz.", "tags": [ "Webhook'lar" ], "x-oyuneks-scope": "webhooks:manage", "parameters": [ { "name": "webhookId", "in": "path", "required": true, "description": "GET /webhooks yanıtındaki abonelik kimliği. Başka bayiye aitse 404 döner.", "schema": { "type": "integer" }, "example": "214" } ], "responses": { "200": { "description": "Başarılı", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "mode" ], "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "requestId": { "type": "string", "maxLength": 26 } } }, "example": { "data": { "deleted": true }, "mode": "live", "requestId": "01K3QF6ZC2M9V0X7NB4TDHR8YE" } } } }, "404": { "description": "* NOT_FOUND — Kayıt ya da uç bulunamadı. Kimliği ve adresi doğrulayın. Başka bayinin siparişi de \"bulunamadı\" döner (varlığını sızdırmayız).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Yetkisiz" }, "403": { "$ref": "#/components/responses/Yasak" }, "429": { "$ref": "#/components/responses/TavanAsimi" }, "500": { "$ref": "#/components/responses/IcHata" }, "503": { "$ref": "#/components/responses/Kapali" } } } } }, "webhooks": { "order.delivered": { "post": { "operationId": "olayOrderDelivered", "summary": "Siparis teslim edildi (kismi teslim de bu olayla gelir)", "description": "İmza: HMAC-SHA256, imzalanan: t + \".\" + HAM istek gövdesi. JSON'i çözüp yeniden serileştirirseniz imza TUTMAZ; ham gövdeyi kullanın (PHP: file_get_contents(\"php://input\")). Bağlantı 3 saniye, toplam 5 saniye. İşi ASENKRON yapın: olayı kaydedip hemen 200 dönün.", "security": [], "parameters": [ { "name": "X-Oyuneks-Event", "in": "header", "required": true, "description": "Olay adı (order.delivered, price.changed, ping...).", "schema": { "type": "string" } }, { "name": "X-Oyuneks-Event-Id", "in": "header", "required": true, "description": "Olay kimliği. AYNI KİMLİK İKİ KEZ GELEBİLİR (ağ hatası sonrası yeniden deneme); ikinci gelişi yok sayın.", "schema": { "type": "string" } }, { "name": "X-Oyuneks-Signature", "in": "header", "required": true, "description": "t=,v1=", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_o184213_d", "type": "order.delivered", "mode": "live", "createdAt": "2026-08-28T14:05:02+03:00", "data": { "orderId": 184213, "externalRef": "SIP-2026-0001", "channel": "dealer-api", "status": "delivered", "total": "197.40", "currency": "TRY", "createdAt": "2026-08-28T14:05:00+03:00", "items": [ { "itemId": "184213-1", "productId": 6, "name": "1020 Cash", "quantity": 2, "status": "delivered", "unitPrice": "98.70", "codeCount": 2 } ] } } } } }, "responses": { "200": { "description": "2xx. Gövde okunmaz, boş yanıt yeterlidir." }, "default": { "description": "8 denemede 2xx alınamazsa olay \"ölü\" sayılır ve gönderim kaydında öyle görünür." } } } }, "order.failed": { "post": { "operationId": "olayOrderFailed", "summary": "Siparis basarisiz/iptal: tutar bakiyeye iade edildi", "description": "İmza: HMAC-SHA256, imzalanan: t + \".\" + HAM istek gövdesi. JSON'i çözüp yeniden serileştirirseniz imza TUTMAZ; ham gövdeyi kullanın (PHP: file_get_contents(\"php://input\")). Bağlantı 3 saniye, toplam 5 saniye. İşi ASENKRON yapın: olayı kaydedip hemen 200 dönün.", "security": [], "parameters": [ { "name": "X-Oyuneks-Event", "in": "header", "required": true, "description": "Olay adı (order.delivered, price.changed, ping...).", "schema": { "type": "string" } }, { "name": "X-Oyuneks-Event-Id", "in": "header", "required": true, "description": "Olay kimliği. AYNI KİMLİK İKİ KEZ GELEBİLİR (ağ hatası sonrası yeniden deneme); ikinci gelişi yok sayın.", "schema": { "type": "string" } }, { "name": "X-Oyuneks-Signature", "in": "header", "required": true, "description": "t=,v1=", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_o184219_f", "type": "order.failed", "mode": "live", "createdAt": "2026-08-28T14:22:10+03:00", "data": { "orderId": 184219, "externalRef": "SIP-2026-0007", "channel": "dealer-api", "status": "failed", "total": "0.00", "currency": "TRY", "items": [ { "itemId": "184219-1", "productId": 1421, "name": "60 UC", "quantity": 1, "status": "failed", "unitPrice": "41.90", "failCode": "TIMEOUT", "failReason": "ZAMAN ASIMI: stok 15 dk icinde saglanamadi", "refund": "41.90" } ] } } } } }, "responses": { "200": { "description": "2xx. Gövde okunmaz, boş yanıt yeterlidir." }, "default": { "description": "8 denemede 2xx alınamazsa olay \"ölü\" sayılır ve gönderim kaydında öyle görünür." } } } }, "price.changed": { "post": { "operationId": "olayPriceChanged", "summary": "Bayi fiyatin degisti", "description": "İmza: HMAC-SHA256, imzalanan: t + \".\" + HAM istek gövdesi. JSON'i çözüp yeniden serileştirirseniz imza TUTMAZ; ham gövdeyi kullanın (PHP: file_get_contents(\"php://input\")). Bağlantı 3 saniye, toplam 5 saniye. İşi ASENKRON yapın: olayı kaydedip hemen 200 dönün.", "security": [], "parameters": [ { "name": "X-Oyuneks-Event", "in": "header", "required": true, "description": "Olay adı (order.delivered, price.changed, ping...).", "schema": { "type": "string" } }, { "name": "X-Oyuneks-Event-Id", "in": "header", "required": true, "description": "Olay kimliği. AYNI KİMLİK İKİ KEZ GELEBİLİR (ağ hatası sonrası yeniden deneme); ikinci gelişi yok sayın.", "schema": { "type": "string" } }, { "name": "X-Oyuneks-Signature", "in": "header", "required": true, "description": "t=,v1=", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_01K3QF6ZC2M9V0X7NB4TDHR8YE", "type": "price.changed", "mode": "live", "createdAt": "2026-08-28T14:30:00+03:00", "data": { "productId": 6, "oldPrice": "98.70", "newPrice": "96.20", "currency": "TRY", "source": "tier" } } } } }, "responses": { "200": { "description": "2xx. Gövde okunmaz, boş yanıt yeterlidir." }, "default": { "description": "8 denemede 2xx alınamazsa olay \"ölü\" sayılır ve gönderim kaydında öyle görünür." } } } }, "stock.changed": { "post": { "operationId": "olayStockChanged", "summary": "Urunun stok durumu degisti", "description": "İmza: HMAC-SHA256, imzalanan: t + \".\" + HAM istek gövdesi. JSON'i çözüp yeniden serileştirirseniz imza TUTMAZ; ham gövdeyi kullanın (PHP: file_get_contents(\"php://input\")). Bağlantı 3 saniye, toplam 5 saniye. İşi ASENKRON yapın: olayı kaydedip hemen 200 dönün.", "security": [], "parameters": [ { "name": "X-Oyuneks-Event", "in": "header", "required": true, "description": "Olay adı (order.delivered, price.changed, ping...).", "schema": { "type": "string" } }, { "name": "X-Oyuneks-Event-Id", "in": "header", "required": true, "description": "Olay kimliği. AYNI KİMLİK İKİ KEZ GELEBİLİR (ağ hatası sonrası yeniden deneme); ikinci gelişi yok sayın.", "schema": { "type": "string" } }, { "name": "X-Oyuneks-Signature", "in": "header", "required": true, "description": "t=,v1=", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_01K3QF6ZC2M9V0X7NB4TDHR8YE", "type": "stock.changed", "mode": "live", "createdAt": "2026-08-28T14:30:00+03:00", "data": { "productId": 6, "oldMode": "count", "newMode": "supplier" } } } } }, "responses": { "200": { "description": "2xx. Gövde okunmaz, boş yanıt yeterlidir." }, "default": { "description": "8 denemede 2xx alınamazsa olay \"ölü\" sayılır ve gönderim kaydında öyle görünür." } } } }, "product.enabled": { "post": { "operationId": "olayProductEnabled", "summary": "Urun yeniden satista", "description": "İmza: HMAC-SHA256, imzalanan: t + \".\" + HAM istek gövdesi. JSON'i çözüp yeniden serileştirirseniz imza TUTMAZ; ham gövdeyi kullanın (PHP: file_get_contents(\"php://input\")). Bağlantı 3 saniye, toplam 5 saniye. İşi ASENKRON yapın: olayı kaydedip hemen 200 dönün.", "security": [], "parameters": [ { "name": "X-Oyuneks-Event", "in": "header", "required": true, "description": "Olay adı (order.delivered, price.changed, ping...).", "schema": { "type": "string" } }, { "name": "X-Oyuneks-Event-Id", "in": "header", "required": true, "description": "Olay kimliği. AYNI KİMLİK İKİ KEZ GELEBİLİR (ağ hatası sonrası yeniden deneme); ikinci gelişi yok sayın.", "schema": { "type": "string" } }, { "name": "X-Oyuneks-Signature", "in": "header", "required": true, "description": "t=,v1=", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_01K3QF6ZC2M9V0X7NB4TDHR8YE", "type": "product.enabled", "mode": "live", "createdAt": "2026-08-28T14:30:00+03:00", "data": { "productId": 1421 } } } } }, "responses": { "200": { "description": "2xx. Gövde okunmaz, boş yanıt yeterlidir." }, "default": { "description": "8 denemede 2xx alınamazsa olay \"ölü\" sayılır ve gönderim kaydında öyle görünür." } } } }, "product.disabled": { "post": { "operationId": "olayProductDisabled", "summary": "Urun satistan cikti", "description": "İmza: HMAC-SHA256, imzalanan: t + \".\" + HAM istek gövdesi. JSON'i çözüp yeniden serileştirirseniz imza TUTMAZ; ham gövdeyi kullanın (PHP: file_get_contents(\"php://input\")). Bağlantı 3 saniye, toplam 5 saniye. İşi ASENKRON yapın: olayı kaydedip hemen 200 dönün.", "security": [], "parameters": [ { "name": "X-Oyuneks-Event", "in": "header", "required": true, "description": "Olay adı (order.delivered, price.changed, ping...).", "schema": { "type": "string" } }, { "name": "X-Oyuneks-Event-Id", "in": "header", "required": true, "description": "Olay kimliği. AYNI KİMLİK İKİ KEZ GELEBİLİR (ağ hatası sonrası yeniden deneme); ikinci gelişi yok sayın.", "schema": { "type": "string" } }, { "name": "X-Oyuneks-Signature", "in": "header", "required": true, "description": "t=,v1=", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_01K3QF6ZC2M9V0X7NB4TDHR8YE", "type": "product.disabled", "mode": "live", "createdAt": "2026-08-28T14:30:00+03:00", "data": { "productId": 1421 } } } } }, "responses": { "200": { "description": "2xx. Gövde okunmaz, boş yanıt yeterlidir." }, "default": { "description": "8 denemede 2xx alınamazsa olay \"ölü\" sayılır ve gönderim kaydında öyle görünür." } } } }, "balance.low": { "post": { "operationId": "olayBalanceLow", "summary": "Bakiye esigin altina dustu", "description": "İmza: HMAC-SHA256, imzalanan: t + \".\" + HAM istek gövdesi. JSON'i çözüp yeniden serileştirirseniz imza TUTMAZ; ham gövdeyi kullanın (PHP: file_get_contents(\"php://input\")). Bağlantı 3 saniye, toplam 5 saniye. İşi ASENKRON yapın: olayı kaydedip hemen 200 dönün.", "security": [], "parameters": [ { "name": "X-Oyuneks-Event", "in": "header", "required": true, "description": "Olay adı (order.delivered, price.changed, ping...).", "schema": { "type": "string" } }, { "name": "X-Oyuneks-Event-Id", "in": "header", "required": true, "description": "Olay kimliği. AYNI KİMLİK İKİ KEZ GELEBİLİR (ağ hatası sonrası yeniden deneme); ikinci gelişi yok sayın.", "schema": { "type": "string" } }, { "name": "X-Oyuneks-Signature", "in": "header", "required": true, "description": "t=,v1=", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_01K3QF6ZC2M9V0X7NB4TDHR8YE", "type": "balance.low", "mode": "live", "createdAt": "2026-08-28T14:31:00+03:00", "data": { "available": "1840.00", "threshold": "2500.00", "currency": "TRY" } } } } }, "responses": { "200": { "description": "2xx. Gövde okunmaz, boş yanıt yeterlidir." }, "default": { "description": "8 denemede 2xx alınamazsa olay \"ölü\" sayılır ve gönderim kaydında öyle görünür." } } } }, "balance.credited": { "post": { "operationId": "olayBalanceCredited", "summary": "Bakiyene yukleme yapildi", "description": "İmza: HMAC-SHA256, imzalanan: t + \".\" + HAM istek gövdesi. JSON'i çözüp yeniden serileştirirseniz imza TUTMAZ; ham gövdeyi kullanın (PHP: file_get_contents(\"php://input\")). Bağlantı 3 saniye, toplam 5 saniye. İşi ASENKRON yapın: olayı kaydedip hemen 200 dönün.", "security": [], "parameters": [ { "name": "X-Oyuneks-Event", "in": "header", "required": true, "description": "Olay adı (order.delivered, price.changed, ping...).", "schema": { "type": "string" } }, { "name": "X-Oyuneks-Event-Id", "in": "header", "required": true, "description": "Olay kimliği. AYNI KİMLİK İKİ KEZ GELEBİLİR (ağ hatası sonrası yeniden deneme); ikinci gelişi yok sayın.", "schema": { "type": "string" } }, { "name": "X-Oyuneks-Signature", "in": "header", "required": true, "description": "t=,v1=", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_c3012301", "type": "balance.credited", "mode": "live", "createdAt": "2026-08-28T15:02:00+03:00", "data": { "amount": "25000.00", "available": "26840.00", "currency": "TRY", "transactionId": 3012301, "createdAt": "2026-08-28T15:01:44+03:00" } } } } }, "responses": { "200": { "description": "2xx. Gövde okunmaz, boş yanıt yeterlidir." }, "default": { "description": "8 denemede 2xx alınamazsa olay \"ölü\" sayılır ve gönderim kaydında öyle görünür." } } } }, "ping": { "post": { "operationId": "olayPing", "summary": "Panelden/API'den \"test et\" denildiğinde gönderilir. Abonelik gerektirmez, kuyruğa girmez, yeniden denenmez. mode alanı \"test\" gelir.", "description": "İmza: HMAC-SHA256, imzalanan: t + \".\" + HAM istek gövdesi. JSON'i çözüp yeniden serileştirirseniz imza TUTMAZ; ham gövdeyi kullanın (PHP: file_get_contents(\"php://input\")). Bağlantı 3 saniye, toplam 5 saniye. İşi ASENKRON yapın: olayı kaydedip hemen 200 dönün.", "security": [], "parameters": [ { "name": "X-Oyuneks-Event", "in": "header", "required": true, "description": "Olay adı (order.delivered, price.changed, ping...).", "schema": { "type": "string" } }, { "name": "X-Oyuneks-Event-Id", "in": "header", "required": true, "description": "Olay kimliği. AYNI KİMLİK İKİ KEZ GELEBİLİR (ağ hatası sonrası yeniden deneme); ikinci gelişi yok sayın.", "schema": { "type": "string" } }, { "name": "X-Oyuneks-Signature", "in": "header", "required": true, "description": "t=,v1=", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_01K3QF6ZC2M9V0X7NB4TDHR8YE", "type": "ping", "mode": "test", "createdAt": "2026-08-28T14:00:00+03:00", "data": { "dealerId": 385841, "message": "Oyuneks bayi webhook testi." } } } } }, "responses": { "200": { "description": "2xx. Gövde okunmaz, boş yanıt yeterlidir." }, "default": { "description": "8 denemede 2xx alınamazsa olay \"ölü\" sayılır ve gönderim kaydında öyle görünür." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "oyxb_live_... | oyxb_test_...", "description": "Bayi Panelinden üretilen anahtar. Önek modu söyler; kapsamlar anahtar başına seçilir." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "API_KAPALI", "YETKISIZ", "BAYI_ASKIDA", "API_ERISIMI_KAPALI", "KAPSAM_YOK", "RATE_LIMITED", "BAD_REQUEST", "NOT_FOUND", "METHOD_NOT_ALLOWED", "INSUFFICIENT_BALANCE", "PRICE_CHANGED", "OUT_OF_STOCK", "INVALID_FIELDS", "INVALID_PLAYER_ID", "LIMIT_EXCEEDED", "PRODUCT_DISABLED", "PRODUCT_NOT_ALLOWED", "NOT_CANCELLABLE", "MIN_QTY", "IDEMPOTENCY_MISMATCH", "ORDER_IN_PROGRESS", "NOT_IMPLEMENTED", "INTERNAL" ], "description": "Sabit hata kodu. Dallanmayı BU alan üzerinden yapın." }, "message": { "type": "string", "description": "İnsan için; zamanla değişebilir." }, "retryable": { "type": "boolean" }, "requestId": { "type": "string" }, "details": { "type": "object", "additionalProperties": true, "description": "Makine okuyabilir ayrıntı (required/available, current, fields...). Boşsa {}." } } } } }, "Me": { "type": "object", "properties": { "dealerId": { "type": "integer" }, "company": { "type": [ "string", "null" ] }, "tier": { "type": [ "string", "null" ] }, "tierId": { "type": [ "integer", "null" ] }, "balance": { "type": "string", "pattern": "^-?[0-9]+\\.[0-9]{2}$", "description": "Para: 2 ondalıklı METİN (\"411.50\")." }, "currency": { "type": "string" }, "limits": { "type": "object", "properties": { "dailyPurchase": { "anyOf": [ { "type": "string", "pattern": "^-?[0-9]+\\.[0-9]{2}$", "description": "Para: 2 ondalıklı METİN (\"411.50\")." }, { "type": "null" } ], "description": "null = günlük limit yok." }, "dailyUsed": { "type": "string", "pattern": "^-?[0-9]+\\.[0-9]{2}$", "description": "Para: 2 ondalıklı METİN (\"411.50\")." }, "maxQtyPerOrder": { "type": "integer" } } }, "apiEnabled": { "type": "boolean" }, "key": { "type": "object", "properties": { "name": { "type": "string" }, "masked": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "catalog:read", "orders:read", "orders:write", "balance:read", "webhooks:manage" ] } }, "rateReadPerMin": { "type": "integer" }, "rateWritePerMin": { "type": "integer" } } }, "apiVersion": { "type": "string" }, "serverTime": { "type": [ "string", "null" ], "format": "date-time" } } }, "Balance": { "type": "object", "properties": { "available": { "type": "string", "pattern": "^-?[0-9]+\\.[0-9]{2}$", "description": "Para: 2 ondalıklı METİN (\"411.50\")." }, "blocked": { "type": "string", "pattern": "^-?[0-9]+\\.[0-9]{2}$", "description": "Para: 2 ondalıklı METİN (\"411.50\")." }, "breakdown": { "type": "object", "properties": { "balance": { "type": "string", "pattern": "^-?[0-9]+\\.[0-9]{2}$", "description": "Para: 2 ondalıklı METİN (\"411.50\")." }, "refundable": { "type": "string", "pattern": "^-?[0-9]+\\.[0-9]{2}$", "description": "Para: 2 ondalıklı METİN (\"411.50\")." }, "bonus": { "type": "string", "pattern": "^-?[0-9]+\\.[0-9]{2}$", "description": "Para: 2 ondalıklı METİN (\"411.50\")." } } }, "pendingDeposits": { "type": "string", "pattern": "^-?[0-9]+\\.[0-9]{2}$", "description": "Para: 2 ondalıklı METİN (\"411.50\")." }, "currency": { "type": "string" }, "asOf": { "type": [ "string", "null" ], "format": "date-time" } } }, "Transaction": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string", "enum": [ "order", "refund", "deposit", "adjustment", "other" ] }, "typeId": { "type": "integer", "description": "Ham hareket tipi (bilinmeyen tipler \"other\" döner, tip kaybolmasın)." }, "amount": { "type": "string", "pattern": "^-?[0-9]+\\.[0-9]{2}$", "description": "Sipariş hareketlerinde EKSİ işaretli, iade/yüklemede artı." }, "balanceAfter": { "type": "string", "pattern": "^-?[0-9]+\\.[0-9]{2}$", "description": "Para: 2 ondalıklı METİN (\"411.50\")." }, "orderId": { "type": [ "integer", "null" ] }, "externalRef": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "Game": { "type": "object", "properties": { "game": { "type": "string", "description": "Slug. Ürün listesinde game süzgecine BU değer verilir." }, "name": { "type": "string" }, "categoryId": { "type": "integer" }, "productCount": { "type": "integer" }, "categories": { "type": "array", "description": "Oyunun altındaki kategoriler. Ürün listesinde category süzgecine categories[].category verilir.", "items": { "type": "object", "properties": { "category": { "type": "string" }, "name": { "type": "string" }, "categoryId": { "type": "integer" }, "productCount": { "type": "integer" } } } } } }, "Stock": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "count", "instant", "supplier", "out" ], "description": "count = elimizdeki kod adedi · instant = tedarikçiden anında · supplier = siparişte çekilir · out = tükendi." }, "count": { "type": "integer" } } }, "RequiredField": { "type": "object", "required": [ "key", "label" ], "properties": { "key": { "type": "string", "description": "fields nesnesinde kullanılacak ANAHTAR. Sıra değil anahtar önemlidir." }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "string" ] }, "minLength": { "type": [ "integer", "null" ] }, "maxLength": { "type": [ "integer", "null" ] }, "required": { "type": "boolean" }, "pattern": { "type": [ "string", "null" ] }, "placeholder": { "type": [ "string", "null" ] } } }, "Product": { "type": "object", "properties": { "productId": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "epin", "topup", "goldbar" ], "description": "goldbar = oyun parası (GB): kod dönmez, karakter adına oyun içi elle teslim edilir." }, "game": { "type": "string" }, "category": { "type": "string" }, "region": { "type": [ "string", "null" ], "description": "Şu an her zaman null: bölge alanı üründe tutulmuyor." }, "listPrice": { "anyOf": [ { "type": "string", "pattern": "^-?[0-9]+\\.[0-9]{2}$", "description": "Para: 2 ondalıklı METİN (\"411.50\")." }, { "type": "null" } ], "description": "Sitedeki perakende fiyat." }, "price": { "type": "string", "pattern": "^-?[0-9]+\\.[0-9]{2}$", "description": "SİZİN bayi fiyatınız (kademe + size özel istisna uygulanmış)." }, "currency": { "type": "string" }, "vatIncluded": { "type": "boolean" }, "stock": { "$ref": "#/components/schemas/Stock" }, "limits": { "type": "object", "properties": { "minQty": { "type": "integer" }, "maxQty": { "type": "integer" } } }, "requiredFields": { "type": "array", "items": { "$ref": "#/components/schemas/RequiredField" } }, "deliveryNote": { "type": [ "string", "null" ], "description": "Yalnız GB ürünlerinde dolu: teslimat yeri notu (örn. \"Zero 7 Sağ Bankadır, trade ile teslim edilir\")." }, "delivery": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "instant", "queued", "manual" ], "description": "manual = GB; operatör oyun içi teslim eder, kod dönmez." }, "etaSeconds": { "type": "integer" } } }, "enabled": { "type": "boolean" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Ürün listesinde her zaman null (güncelleme damgası tutulmuyor); delta uçta gerçek değer döner." } } }, "PriceRow": { "type": "object", "properties": { "productId": { "type": "integer" }, "listPrice": { "anyOf": [ { "type": "string", "pattern": "^-?[0-9]+\\.[0-9]{2}$", "description": "Para: 2 ondalıklı METİN (\"411.50\")." }, { "type": "null" } ] }, "price": { "type": "string", "pattern": "^-?[0-9]+\\.[0-9]{2}$", "description": "Para: 2 ondalıklı METİN (\"411.50\")." }, "currency": { "type": "string" }, "stock": { "$ref": "#/components/schemas/Stock" }, "enabled": { "type": "boolean" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "OrderCode": { "type": "object", "properties": { "code": { "type": "string" }, "serial": { "type": [ "string", "null" ] }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "OrderItem": { "type": "object", "properties": { "itemId": { "type": "string", "description": "\"-\" biçiminde." }, "productId": { "type": "integer" }, "name": { "type": "string" }, "quantity": { "type": "integer" }, "unitPrice": { "type": "string", "pattern": "^-?[0-9]+\\.[0-9]{2}$", "description": "Para: 2 ondalıklı METİN (\"411.50\")." }, "status": { "type": "string", "enum": [ "processing", "delivered", "cancelled", "failed" ] }, "codes": { "type": "array", "items": { "$ref": "#/components/schemas/OrderCode" }, "description": "E-pin kalemlerinde teslim edilen kodlar. Webhook gövdesinde ASLA gönderilmez." }, "receipt": { "type": [ "string", "null" ], "description": "Top-up kalemlerinde makbuz/referans (kod yerine)." }, "failCode": { "type": [ "string", "null" ], "enum": [ "TIMEOUT", "CANCELLED", null ] }, "failReason": { "type": [ "string", "null" ] } } }, "Order": { "type": "object", "properties": { "orderId": { "type": "integer" }, "externalRef": { "type": [ "string", "null" ] }, "channel": { "type": "string", "enum": [ "dealer-api", "dealer-panel", "web" ] }, "status": { "type": "string", "enum": [ "processing", "delivered", "partially_delivered", "cancelled", "failed" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "total": { "type": "string", "pattern": "^-?[0-9]+\\.[0-9]{2}$", "description": "Para: 2 ondalıklı METİN (\"411.50\")." }, "balanceAfter": { "anyOf": [ { "type": "string", "pattern": "^-?[0-9]+\\.[0-9]{2}$", "description": "Para: 2 ondalıklı METİN (\"411.50\")." }, { "type": "null" } ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" } } } }, "OrderCreateRequest": { "type": "object", "required": [ "items" ], "properties": { "externalRef": { "type": "string", "maxLength": 64, "description": "Kendi sipariş numaranız; raporlarda, cari harekette ve webhook gövdesinde geri döner." }, "waitForStock": { "type": "boolean", "default": true, "description": "false: stok yetmiyorsa sipariş hiç başlamaz (OUT_OF_STOCK)." }, "items": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "object", "required": [ "productId", "quantity" ], "properties": { "productId": { "type": "integer" }, "quantity": { "type": "integer", "minimum": 1 }, "fields": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Ürünün requiredFields şemasındaki anahtarlar." }, "expectedPrice": { "anyOf": [ { "type": "string", "pattern": "^-?[0-9]+\\.[0-9]{2}$", "description": "Para: 2 ondalıklı METİN (\"411.50\")." }, { "type": "null" } ], "description": "Fiyat kilidi: farklıysa sipariş VERİLMEZ (PRICE_CHANGED)." } } } } } }, "OrderCancelRequest": { "type": "object", "properties": { "reason": { "type": "string", "description": "İptal gerekçesi (kayda geçer)." } } }, "ValidateRequest": { "type": "object", "required": [ "productId" ], "properties": { "productId": { "type": "integer" }, "fields": { "type": "object", "additionalProperties": { "type": "string" } } } }, "ValidateResult": { "type": "object", "properties": { "supported": { "type": "boolean", "description": "false: üründe önceden doğrulama yok (sipariş vermeyi engellemez)." }, "valid": { "type": [ "boolean", "null" ], "description": "null: şu an kontrol edilemedi (satışı engellemez)." }, "nickname": { "type": [ "string", "null" ] }, "validUntil": { "type": [ "string", "null" ], "format": "date-time" }, "requiredFields": { "type": "array", "items": { "$ref": "#/components/schemas/RequiredField" } }, "message": { "type": [ "string", "null" ] }, "fieldErrors": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "Statement": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "currency": { "type": "string" }, "openingBalance": { "type": "string", "pattern": "^-?[0-9]+\\.[0-9]{2}$", "description": "Para: 2 ondalıklı METİN (\"411.50\")." }, "deposits": { "type": "string", "pattern": "^-?[0-9]+\\.[0-9]{2}$", "description": "Para: 2 ondalıklı METİN (\"411.50\")." }, "orders": { "type": "string", "pattern": "^-?[0-9]+\\.[0-9]{2}$", "description": "Para: 2 ondalıklı METİN (\"411.50\")." }, "refunds": { "type": "string", "pattern": "^-?[0-9]+\\.[0-9]{2}$", "description": "Para: 2 ondalıklı METİN (\"411.50\")." }, "other": { "type": "string", "pattern": "^-?[0-9]+\\.[0-9]{2}$", "description": "Para: 2 ondalıklı METİN (\"411.50\")." }, "closingBalance": { "type": "string", "pattern": "^-?[0-9]+\\.[0-9]{2}$", "description": "Para: 2 ondalıklı METİN (\"411.50\")." }, "count": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "date": { "type": [ "string", "null" ], "format": "date-time" }, "typeId": { "type": "integer" }, "amount": { "type": "string", "pattern": "^-?[0-9]+\\.[0-9]{2}$", "description": "Para: 2 ondalıklı METİN (\"411.50\")." }, "balanceAfter": { "type": "string", "pattern": "^-?[0-9]+\\.[0-9]{2}$", "description": "Para: 2 ondalıklı METİN (\"411.50\")." }, "orderId": { "type": [ "integer", "null" ] }, "description": { "type": [ "string", "null" ] } } } }, "note": { "type": "string" } } }, "Invoice": { "type": "object", "properties": { "invoiceId": { "type": "integer" }, "number": { "type": [ "string", "null" ] }, "numbers": { "type": "array", "items": { "type": "string" } }, "date": { "type": [ "string", "null" ], "format": "date-time" }, "type": { "type": "string" }, "orderNo": { "type": "string" }, "total": { "type": "string", "pattern": "^-?[0-9]+\\.[0-9]{2}$", "description": "Para: 2 ondalıklı METİN (\"411.50\")." }, "vat": { "type": "string", "pattern": "^-?[0-9]+\\.[0-9]{2}$", "description": "Para: 2 ondalıklı METİN (\"411.50\")." }, "currency": { "type": "string" }, "pdfUrl": { "type": "null", "description": "Henüz API üzerinden verilmiyor." }, "panelUrl": { "type": "string" } } }, "WebhookSubscription": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "order.delivered", "order.failed", "price.changed", "stock.changed", "product.enabled", "product.disabled", "balance.low", "balance.credited" ] } }, "status": { "type": "string", "enum": [ "active", "suspended" ] }, "secretMasked": { "type": [ "string", "null" ], "description": "Ham sır BU UÇTA DÖNMEZ." }, "failStreak": { "type": "integer" }, "lastSuccessAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastFailureAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "WebhookSaveRequest": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https://", "description": "Yalnız https; localhost ve özel ağ adresleri reddedilir (SSRF)." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "order.delivered", "order.failed", "price.changed", "stock.changed", "product.enabled", "product.disabled", "balance.low", "balance.credited" ] }, "description": "Boş bırakılırsa varsayılan set uygulanır. Bilinmeyen ad 400 döner." } } }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "integer" }, "eventId": { "type": "string" }, "type": { "type": "string" }, "channel": { "type": "string", "enum": [ "webhook", "email" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "status": { "type": "string", "enum": [ "pending", "sent", "dead" ] }, "attempts": { "type": "integer" }, "httpCode": { "type": [ "integer", "null" ] }, "durationMs": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "nextAttemptAt": { "type": [ "string", "null" ], "format": "date-time" }, "sentAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "WebhookRetryPolicy": { "type": "object", "properties": { "maxAttempts": { "type": "integer" }, "backoffMinutes": { "type": "array", "items": { "type": "integer" } }, "note": { "type": "string" } } }, "WebhookSignatureInfo": { "type": "object", "properties": { "header": { "type": "string" }, "format": { "type": "string" }, "algorithm": { "type": "string" }, "signedPayload": { "type": "string" }, "verify": { "type": "string" }, "tolerance": { "type": "string" } } }, "WebhookEvent": { "type": "object", "required": [ "id", "type", "mode", "createdAt", "data" ], "properties": { "id": { "type": "string", "description": "Olay kimliği. AYNI KİMLİK İKİ KEZ GELEBİLİR: bununla tekilleştirin." }, "type": { "type": "string", "enum": [ "order.delivered", "order.failed", "price.changed", "stock.changed", "product.enabled", "product.disabled", "balance.low", "balance.credited", "ping" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "additionalProperties": true, "description": "Olaya göre değişir; kalemlerde kod YERİNE codeCount bulunur." } } } }, "headers": { "XRequestId": { "description": "İsteğin kimliği (26 karakter). Destek kaydında bu numarayı verin, istek tek sorguyla bulunur.", "schema": { "type": "string" } }, "XRateLimitLimit": { "description": "Bu dakika için geçerli tavan (okuma ve yazma AYRI pencere).", "schema": { "type": "string" } }, "XRateLimitRemaining": { "description": "Bu dakika içinde kalan istek hakkı.", "schema": { "type": "string" } }, "XRateLimitReset": { "description": "Pencerenin sıfırlanacağı zaman (unix saniye).", "schema": { "type": "string" } }, "RetryAfter": { "description": "Yalnız 429 yanıtında: kaç saniye beklenmeli.", "schema": { "type": "string" } }, "ETag": { "description": "Katalog uçlarında: sonraki istekte If-None-Match ile geri gönderin.", "schema": { "type": "string" } }, "IdempotentReplayed": { "description": "true ise bu yanıt ÖNCEKİ isteğin saklanan sonucudur; yeni sipariş OLUŞMADI.", "schema": { "type": "string" } } }, "responses": { "Yetkisiz": { "description": "HTTP 401\n* YETKISIZ — Anahtar yok, geçersiz, iptal edilmiş, IP izinli değil ya da hesap bayi değil. Panelden anahtarı ve IP listesini kontrol edin. Anahtar sızdıysa iptal edip yenisini üretin.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Yasak": { "description": "HTTP 403\n* BAYI_ASKIDA — Bayilik askıya alınmış. Destek ile görüşülmeli; tekrar denemek çözmez.\n* API_ERISIMI_KAPALI — Bayilik aktif ama hesapta API erişimi kapalı. Bayi temsilcinizle görüşün; erişim yönetim tarafından açılır.\n* KAPSAM_YOK — Anahtar geçerli ama bu uç için gereken yetki kapsamı seçilmemiş. Panelden bu kapsamı içeren yeni bir anahtar üretin (kapsam sonradan eklenemez).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Bulunamadi": { "description": "HTTP 404\n* NOT_FOUND — Kayıt ya da uç bulunamadı. Kimliği ve adresi doğrulayın. Başka bayinin siparişi de \"bulunamadı\" döner (varlığını sızdırmayız).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Cakisma": { "description": "HTTP 409\n* IDEMPOTENCY_MISMATCH — Aynı Idempotency-Key daha önce FARKLI bir gövdeyle kullanıldı. Her yeni sipariş için yeni anahtar üretin (kendi sipariş numaranız + deneme sayacı iyi bir kalıp).\n* ORDER_IN_PROGRESS — Aynı anahtarla bir sipariş şu an işleniyor. Birkaç saniye bekleyip GET /orders/by-ref/{externalRef} ile sonucu okuyun.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "IsKuraliRed": { "description": "HTTP 422\n* INSUFFICIENT_BALANCE — Bakiye yetersiz. details.required ve details.available tutarları yanıtta döner. Bakiye yükleyip tekrar deneyin.\n* PRICE_CHANGED — Gönderdiğiniz expectedPrice güncel fiyattan farklı; sipariş VERİLMEDİ. details.current güncel fiyatı taşır. Kataloğu tazeleyip yeni fiyatla tekrar deneyin.\n* OUT_OF_STOCK — Stok yetersiz (waitForStock=false gönderildi). Bir süre sonra tekrar deneyin ya da waitForStock=true ile kuyruğa alın.\n* INVALID_FIELDS — Zorunlu alanlar eksik ya da uzunluk kısıtına uymuyor. details.fields hatalı alanları listeler. Şemayı GET /catalog/products/{productId} ucundan okuyun.\n* INVALID_PLAYER_ID — Oyuncu bilgisi tedarikçi tarafında doğrulanamadı. Sipariş öncesi POST /orders/validate ile kontrol edin; müşteriden doğru kimliği isteyin.\n* LIMIT_EXCEEDED — Günlük sipariş limiti ya da kalem başına adet tavanı aşıldı. GET /me ucundaki limits alanına bakın; günlük limit gece sıfırlanır.\n* PRODUCT_DISABLED — Ürün satışta değil ya da fiyatı tanımlı değil. Kataloğu tazeleyin; ürün geri açıldığında product.enabled olayı gelir.\n* PRODUCT_NOT_ALLOWED — Ürün bayi kanalından satılamaz. Bu ürünler katalog uçlarında da listelenmez; sipariş gövdesinden çıkarın.\n* NOT_CANCELLABLE — GB (oyun parası) kalemi bu uçtan iptal edilemez; teslimat elle yapılır. İptal için destek ekibine yazın. Aynı siparişteki e-pin/top-up kalemleri normal şekilde iptal edilir.\n* MIN_QTY — Ürünün asgari sipariş adedinin altında kalındı. Katalogdaki limits.minQty değerini kullanın.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "TavanAsimi": { "description": "HTTP 429\n* RATE_LIMITED — İstek tavanı aşıldı. Retry-After başlığındaki saniye kadar bekleyin. Okuma ve yazma tavanları AYRI penceredir.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "IcHata": { "description": "HTTP 500\n* INTERNAL — Beklenmeyen sunucu hatası. Tekrar deneyin; sürerse X-Request-Id ile destek kaydı açın.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Kapali": { "description": "HTTP 503\n* API_KAPALI — Bayi API servisi geçici olarak kapatıldı (bakım). Bir süre sonra tekrar deneyin; kod tarafında değişiklik gerekmez.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }