{ "openapi": "3.1.0", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "Kevmi — sunucu API'si", "version": "2026-10-23.12", "description": "Kevmi API: Telegram girişi, oturumlar, satıcı faturaları, şifreli alıcı ödeme sayfası, destek, bildirimler, uygulamalar ve webhook teslimatı. Yalnızca tek seferlik doğrudan ödemeler. JSON yanıtları no-store kullanır. Zaman damgaları, aksi belirtilmedikçe UTC Unix milisaniyesidir. Canlı ödeme, yapılandırılmış harici bir kapı kullanır; kart ve banka kodu alanları tarayıcıda şifrelenir ve yalnızca kapı tarafından çözülür. Yeni ücretlendirmeler, en son satıcı web sitesi uygulamasının onaylanmasını gerektirir. Fatura oluşturmak alıcıyı ücretlendirmez.", "x-updated-at": "2026-10-23" }, "servers": [ { "url": "https://kevmi.one", "description": "Genel proje kaynağı; barındırma platformu ek erişim kontrolleri uygulayabilir." } ], "externalDocs": { "description": "Genel ürün dokümantasyonu", "url": "https://kevmi.one/docs" }, "tags": [ { "name": "Service", "description": "Genel hizmet durumu." }, { "name": "Auth", "description": "Kayıt ve giriş, doğrulanmış Telegram akışını paylaşır." }, { "name": "Account", "description": "Yalnızca geçerli kullanıcı için ayarlar." }, { "name": "Payment links", "description": "Geçerli mağaza için sunucu faturaları. Fiyat, para birimi, KDV mükellefi, satıcı adı ve hesaplama değiştirilemez." }, { "name": "Checkout", "description": "Hesap olmadan bir fatura okuyun. Ödeme kullanılabilirliği ayrıca kontrol edilir." }, { "name": "Support", "description": "Genel bilgi tabanı ve geçerli kullanıcının destek talepleri." }, { "name": "Notifications", "description": "Hesap olay merkezi, web sitesi okuma durumu ve bağımsız Telegram teslimat durumu." }, { "name": "Telegram", "description": "Bot webhook'u; ödeme webhook'u değil." }, { "name": "Disabled payments", "description": "Desteklenmeyen eski para yolları ve ödeme yürütmesi. Genel ödeme akışının kendi belgelenmiş uç noktaları vardır." }, { "name": "Merchant API", "description": "Kapsamlı sunucudan sunucuya faturalar ve değiştirilemez olay geçmişi." }, { "name": "Webhooks", "description": "Doğrulanmış HTTPS uç noktaları, imzalı olaylar, teslimat denemeleri ve yeniden denemeler." }, { "name": "Applications", "description": "Kimlik doğrulamalı web sitesi uygulamaları ve bireysel izleme." }, { "name": "Moderation", "description": "İzin listesindeki Telegram moderatörleri; her karar sürüm kontrolünden geçer." }, { "name": "Gateway events", "description": "Kaynak yerel kapı olayları doğrulanır, ardından yetkili ödeme, kimlik doğrulamalı sunucu aktarımı üzerinden okunur. Satıcıya yönelik webhook'lar ayrı bir imza ve teslimat kuyruğu kullanır." } ], "security": [], "x-disabled-route-prefixes": [ "/api/payments", "/api/payouts", "/api/gateway", "/api/linzapay" ], "x-disabled-route-behavior": "Legacy unscoped direct-money routes and payout execution remain disabled. Authenticated /api/v1/payments creates invoices; /api/checkout/{token} exposes the separate buyer checkout flow. POST /api/gateway/webhook accepts signed gateway events.", "paths": { "/api/config": { "get": { "tags": [ "Service" ], "operationId": "getConfig", "summary": "Güncel entegrasyon hazırlığı", "responses": { "200": { "description": "Sırlar olmadan yapılandırma.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Config" } } } }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/health": { "get": { "tags": [ "Service" ], "operationId": "getHealth", "summary": "API ve D1 tablo durumu", "description": "not_configured, status=ok değerine sahip olabilir: genel sayfalar ve arama, DB olmadan çalışabilir. Kullanılamayan tablolara sahip yapılandırılmış bir DB, 503/degraded döndürür. Bu yanıt, Telegram veya model ağ bağlantısını test etmez.", "responses": { "200": { "description": "Depolama hazır veya not_configured.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } }, "503": { "description": "D1 kullanılamıyor veya beklenmeyen bir hizmet hatası oluştu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Health" }, { "$ref": "#/components/schemas/Error" } ] } } } } } } }, "/api/auth/me": { "get": { "tags": [ "Auth" ], "operationId": "getCurrentSession", "summary": "Geçerli oturum ve CSRF", "security": [ {}, { "cookieSession": [] } ], "responses": { "200": { "description": "Geçerli bir oturum olmadığında authenticated=false.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Anonymous" }, { "$ref": "#/components/schemas/CurrentSession" } ] } } } }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/auth/telegram/start": { "post": { "tags": [ "Auth" ], "operationId": "startTelegramLogin", "summary": "Giriş veya kayıt başlat", "description": "300 saniyelik bir meydan okuma ve bir HttpOnly tarayıcı kanıtı çerezi oluşturur; karmalanmış adres başına dakikada en fazla altı başlatma. Web sitesindeki ve özel bot sohbetindeki altı haneli kodu karşılaştırın.", "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "APP_ORIGIN ile birebir eşleşmelidir. Sec-Fetch-Site: cross-site reddedilir. Sunucu CORS erişimi sağlamaz.", "schema": { "type": "string", "format": "uri" } } ], "requestBody": { "required": true, "description": "JSON nesnesi. En fazla 16.384 bayt. Bilinmeyen alanlar reddedilir.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyObject" } } } }, "responses": { "201": { "description": "Giriş talebi oluşturuldu; kanıt çerezi bunu orijinal tarayıcıya bağlar.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Set-Cookie": { "schema": { "type": "string" }, "description": "Güvenli; HttpOnly; SameSite=Lax; Path=/. JavaScript oturum değerine erişemez. Girişi tamamlamak tarayıcı kanıtı çerezi de temizler." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginChallenge" } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "413": { "description": "Gövde 16.384 baytı aşıyor; /api/support/ask ve Telegram webhook'u için sınır 65.536 bayttır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json gereklidir.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Hız sınırı aşıldı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "Sunucu her zaman 60 döndürür; bu, saatlik kotanın dolduğunu garanti etmez." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/auth/telegram/complete": { "post": { "tags": [ "Auth" ], "operationId": "completeTelegramLogin", "summary": "Doğrulanmış bir girişi tamamla", "description": "Başlangıçtaki kanıt çerezi ve aynı tarayıcıyı gerektirir. Beklemede 202 döndürür. Bot onayından sonra istek, 24 saatlik bir oturum düzenler. Meydan okuma başına dakikada en fazla 90 kontrol. İstemci tarafından sağlanan bir Telegram kimliği kabul edilmez.", "security": [ { "browserProof": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "APP_ORIGIN ile birebir eşleşmelidir. Sec-Fetch-Site: cross-site reddedilir. Sunucu CORS erişimi sağlamaz.", "schema": { "type": "string", "format": "uri" } } ], "requestBody": { "required": true, "description": "JSON nesnesi. En fazla 16.384 bayt. Bilinmeyen alanlar reddedilir.", "content": { "application/json": { "schema": { "type": "object", "properties": { "challengeId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, "required": [ "challengeId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Hesap oluşturuldu veya güncellendi ve oturum düzenlendi.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Set-Cookie": { "schema": { "type": "string" }, "description": "Güvenli; HttpOnly; SameSite=Lax; Path=/. JavaScript oturum değerine erişemez. Girişi tamamlamak tarayıcı kanıtı çerezi de temizler." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompletedLogin" } } } }, "202": { "description": "Telegram'da onay bekleniyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "pending" } }, "required": [ "status" ], "additionalProperties": false } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "409": { "description": "Giriş talebi kullanıldı veya iptal edildi, kimlik doğrulanmadı veya bir destek talebi çakışıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "410": { "description": "Beş dakikalık giriş talebi süresi doldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_EXPIRED" ] }, "413": { "description": "Gövde 16.384 baytı aşıyor; /api/support/ask ve Telegram webhook'u için sınır 65.536 bayttır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json gereklidir.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Hız sınırı aşıldı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "Sunucu her zaman 60 döndürür; bu, saatlik kotanın dolduğunu garanti etmez." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/auth/logout": { "post": { "tags": [ "Auth" ], "operationId": "logoutCurrentSession", "summary": "Geçerli oturumu sonlandır", "description": "Gövde gerekmez veya okunmaz. Botun /logout komutu ayrıca tüm hesap oturumlarını sonlandırır.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "APP_ORIGIN ile birebir eşleşmelidir. Sec-Fetch-Site: cross-site reddedilir. Sunucu CORS erişimi sağlamaz.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "GET /api/auth/me veya başarılı giriş tamamlamadan gelen geçerli oturum belirteci.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "responses": { "200": { "description": "Oturum silindi ve çerez temizlendi.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Set-Cookie": { "schema": { "type": "string" }, "description": "Güvenli; HttpOnly; SameSite=Lax; Path=/. JavaScript oturum değerine erişemez. Girişi tamamlamak tarayıcı kanıtı çerezi de temizler." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "loggedOut": { "type": "boolean", "const": true } }, "required": [ "loggedOut" ], "additionalProperties": false } } } }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/account/settings": { "get": { "tags": [ "Account" ], "operationId": "getAccountSettings", "summary": "Geçerli kullanıcı ayarları", "security": [ { "cookieSession": [] } ], "responses": { "200": { "description": "Geçerli kullanıcı profillerinin genel alanları.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "parameters": [ { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Tarayıcı oturumu için sahip olunan bir mağaza seçin. İlk mağazayı kullanmak için atlayın. API anahtarları bu başlığı yok sayar ve her zaman değişmez mağaza bağlamasını kullanır. all değeri salt okunurdur ve yalnızca gösterge paneli ve fatura listesi uç noktaları tarafından desteklenir." } ] }, "patch": { "tags": [ "Account" ], "operationId": "updateAccountSettings", "summary": "Mağaza adını, KDV mükellefini veya bildirimleri değiştir", "description": "Tüm alanlar isteğe bağlıdır: kısmi yama. vatPayer kaydetmek finansal bir işlem oluşturmaz. Ödemeler ve ödeme anahtarları, kapı kullanılabilirliğini değil tercihleri kontrol eder.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "APP_ORIGIN ile birebir eşleşmelidir. Sec-Fetch-Site: cross-site reddedilir. Sunucu CORS erişimi sağlamaz.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "GET /api/auth/me veya başarılı giriş tamamlamadan gelen geçerli oturum belirteci.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Tarayıcı oturumu için sahip olunan bir mağaza seçin. İlk mağazayı kullanmak için atlayın. API anahtarları bu başlığı yok sayar ve her zaman değişmez mağaza bağlamasını kullanır. all değeri salt okunurdur ve yalnızca gösterge paneli ve fatura listesi uç noktaları tarafından desteklenir." } ], "requestBody": { "required": true, "description": "JSON nesnesi. En fazla 16.384 bayt. Bilinmeyen alanlar reddedilir.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingsPatch" } } } }, "responses": { "200": { "description": "Profil güncellendi.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "413": { "description": "Gövde 16.384 baytı aşıyor; /api/support/ask ve Telegram webhook'u için sınır 65.536 bayttır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json gereklidir.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/support/ask": { "post": { "tags": [ "Support" ], "operationId": "askDocumentation", "summary": "Eksiksiz genel bilgi tabanından yanıt", "description": "Opsiyonel kimliği doğrulanmış hesap okumalarıyla belge yardımı. includeAccount=true olmadan özel hesap araçları etkinleştirilmez. Sınırlı read_account aracı mağazaları, faturaları ve doğrulanmış makbuzları, olayları, web sitesi başvurularını ve yanıtlı destek taleplerini okuyabilir. Sahip ve mağaza filtreleri sunucuda uygulanır; araçlar fon taşıyamaz, ayarları değiştiremez veya entegrasyon sırlarını döndüremez. Sonuçlar sayfalandırılır; eksik bir örnek tam işlem geçmişi değildir. Sağlayıcı veya çıktı hataları etiketli belge aramasına geri döner. Küresel bir üretim kotası ve IP başına istek sınırı uygulanır.", "parameters": [ { "name": "Origin", "in": "header", "required": false, "description": "APP_ORIGIN ile birebir eşleşmelidir. Sec-Fetch-Site: cross-site reddedilir. Sunucu CORS erişimi sağlamaz.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": false, "schema": { "type": "string" }, "description": "includeAccount=true olduğunda gereklidir." }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Sahip olunan mağaza kimliği veya tümü; hesap erişimi devre dışı olduğunda yok sayılır." } ], "requestBody": { "required": true, "description": "65.536 bayta kadar JSON nesnesi. Bilinmeyen alanlar reddedilir. Metin uzunlukları kırpmadan sonra kontrol edilir.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportQuestion" } } } }, "responses": { "200": { "description": "Doğrulanmış makale bağlantılarıyla bir yanıt veya eşleşen belgeler.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportAnswer" } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "413": { "description": "Gövde 16.384 baytı aşıyor; /api/support/ask ve Telegram webhook'u için sınır 65.536 bayttır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json gereklidir.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Hız sınırı aşıldı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "Sunucu her zaman 60 döndürür; bu, saatlik kotanın dolduğunu garanti etmez." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/support/tickets": { "get": { "tags": [ "Support" ], "operationId": "listOwnTickets", "summary": "Sahip olunan destek isteklerinin son 30'u", "security": [ { "cookieSession": [] } ], "responses": { "200": { "description": "createdAt'e göre en yenisi önce; son 30 kaydı döndürür.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "tickets": { "type": "array", "maxItems": 30, "items": { "$ref": "#/components/schemas/Ticket" } } }, "required": [ "tickets" ], "additionalProperties": false } } } }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } }, "post": { "tags": [ "Support" ], "operationId": "createOwnTicket", "summary": "Bir destek isteği kaydet", "description": "Kullanıcı başına saatte en fazla 6 istek, site ve bot için paylaşılan kota. Kaydetme, hesapta bir istek oluşturur. Durumu netleştirmek için numarasını kullanın. Talebe doğrudan bağlantı içeren ayrı bir kalıcı yönetici uyarısı kuyruğa alınır; geçici teslimat arızaları yeniden denenir. Uzman yanıtları Telegram bildirimleri devre dışı olsa bile hesapta okunabilir kalır.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "APP_ORIGIN ile birebir eşleşmelidir. Sec-Fetch-Site: cross-site reddedilir. Sunucu CORS erişimi sağlamaz.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "GET /api/auth/me veya başarılı giriş tamamlamadan gelen geçerli oturum belirteci.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "requestBody": { "required": true, "description": "JSON nesnesi. En fazla 16.384 bayt. Bilinmeyen alanlar reddedilir.", "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "minLength": 1, "x-trimmedMaxLength": 120, "x-trimmedMinLength": 1, "description": "Çevreleyen boşluklar kırpılır. Kırpmadan sonra uzunluk: 1-120 karakter. Sekmeler ve satır sonları dışındaki kontrol karakterleri yasaktır." }, "message": { "type": "string", "minLength": 5, "x-trimmedMaxLength": 4000, "x-trimmedMinLength": 5, "description": "Çevreleyen boşluklar kırpılır. Kırpmadan sonra uzunluk: 5-4.000 karakter. Sekmeler ve satır sonları dışındaki kontrol karakterleri yasaktır." } }, "required": [ "subject", "message" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Destek isteği kaydedildi.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketResponse" } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "409": { "description": "Giriş talebi kullanıldı veya iptal edildi, kimlik doğrulanmadı veya bir destek talebi çakışıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "413": { "description": "Gövde 16.384 baytı aşıyor; /api/support/ask ve Telegram webhook'u için sınır 65.536 bayttır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json gereklidir.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Hız sınırı aşıldı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "Sunucu her zaman 60 döndürür; bu, saatlik kotanın dolduğunu garanti etmez." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/support/tickets/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^tkt_[a-f0-9-]{36}$" }, "description": "Sahip olunan bir destek isteğinin tanımlayıcısı." } ], "get": { "tags": [ "Support" ], "operationId": "getOwnTicket", "summary": "Sahip olunan bir destek isteğini oku", "security": [ { "cookieSession": [] } ], "responses": { "200": { "description": "Başka bir kullanıcının isteği ve eksik bir istek ikisi de 404 döndürür.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketResponse" } } } }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "404": { "description": "Kayıt eksik, genel belirteç geçersiz veya istenen kayıt başka bir kullanıcıya ait.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } }, "patch": { "tags": [ "Support" ], "operationId": "closeOwnTicket", "summary": "Sahip olunan bir destek isteğini kapat", "description": "İzin verilen tek değişiklik status=closed'dır. Bu API istekleri yeniden açmaz, mesajları düzenlemez veya operatör yanıtları göndermez.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "APP_ORIGIN ile birebir eşleşmelidir. Sec-Fetch-Site: cross-site reddedilir. Sunucu CORS erişimi sağlamaz.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "GET /api/auth/me veya başarılı giriş tamamlamadan gelen geçerli oturum belirteci.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "requestBody": { "required": true, "description": "JSON nesnesi. En fazla 16.384 bayt. Bilinmeyen alanlar reddedilir.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "closed" } }, "required": [ "status" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Destek isteği kapatıldı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "closed": { "type": "boolean", "const": true } }, "required": [ "closed" ], "additionalProperties": false } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "Kayıt eksik, genel belirteç geçersiz veya istenen kayıt başka bir kullanıcıya ait.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "413": { "description": "Gövde 16.384 baytı aşıyor; /api/support/ask ve Telegram webhook'u için sınır 65.536 bayttır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json gereklidir.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/notifications": { "get": { "tags": [ "Notifications" ], "operationId": "listOwnNotifications", "summary": "Sahip olunan bildirimlerden oluşan bir sayfa", "description": "En fazla 30 kayıt, createdAt DESC ardından id DESC ile sıralanır. Listeleme readAt'i değiştirmez veya teslimatı tetiklemez. unreadCount, geçerli kullanıcının sayfalar genelinde toplam okunmamış sayısıdır. Sahip alanları, Telegram kimliği ve sırlar hariç tutulur.", "security": [ { "cookieSession": [] } ], "parameters": [ { "name": "unread", "in": "query", "description": "1 yalnızca okunmamışları seçer; 0 veya atlanmış bir değer tüm olayları seçer.", "schema": { "type": "string", "enum": [ "0", "1" ], "default": "0" } }, { "name": "cursor", "in": "query", "description": "Önceki yanıttan nextCursor. URLSearchParams üzerinden değiştirilmeden iletin; biçim createdAt:id, createdAt milisaniye cinsinden güvenli bir tam sayı olarak.", "schema": { "type": "string", "pattern": "^\\d{1,16}:ntf_[A-Za-z0-9-]{1,80}$" } } ], "responses": { "200": { "description": "Bağımsız okuma ve teslimat durumlarına sahip olaylar.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationsPage" } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/notifications/read": { "patch": { "tags": [ "Notifications" ], "operationId": "markOwnNotificationsRead", "summary": "Sahip olunan bildirimleri okunmuş olarak işaretle", "description": "Ya ids kabul eder ya da before ile birlikte all:true. before, son gözlemlenen olayın zamanıdır ve sunucu saatini aşamaz. Daha yeni olaylar okunmamış kalır. İstek idempotenttir: mevcut readAt değerleri değişmez. Diğer kullanıcıların ve eksik kimlikler ne değiştirilir ne de açıklanır. Telegram durumu ve sentAt değişmeden kalır.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "APP_ORIGIN ile birebir eşleşmelidir. Sec-Fetch-Site: cross-site reddedilir. Sunucu CORS erişimi sağlamaz.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "GET /api/auth/me veya başarılı giriş tamamlamadan gelen geçerli oturum belirteci.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "requestBody": { "required": true, "description": "JSON nesnesi. En fazla 16.384 bayt. Bilinmeyen alanlar reddedilir.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadNotifications" } } } }, "responses": { "200": { "description": "Yeni okunan olayların sayısı, işlem süresi ve geçerli okunmamış sayı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadNotificationsResult" } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "413": { "description": "Gövde 16.384 baytı aşıyor; /api/support/ask ve Telegram webhook'u için sınır 65.536 bayttır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json gereklidir.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/notifications/test": { "post": { "tags": [ "Notifications" ], "operationId": "testOwnNotification", "summary": "Hesabın Telegram'ına bir test bildirimi gönder", "description": "Bir mesajı sıraya alır ve teslimat dener. Kullanıcı başına saatte en fazla üç. Test bir ödeme bildirimi değildir ve bakiyeyi değiştirmez. HTTP 202 teslimatı onaylamaz; bildirim listesini kontrol edin.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "APP_ORIGIN ile birebir eşleşmelidir. Sec-Fetch-Site: cross-site reddedilir. Sunucu CORS erişimi sağlamaz.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "GET /api/auth/me veya başarılı giriş tamamlamadan gelen geçerli oturum belirteci.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "requestBody": { "required": true, "description": "JSON nesnesi. En fazla 16.384 bayt. Bilinmeyen alanlar reddedilir.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyObject" } } } }, "responses": { "202": { "description": "Sıraya alma sonucu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "queued": { "type": "boolean" }, "id": { "type": [ "string", "null" ] } }, "required": [ "queued" ], "additionalProperties": false } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "413": { "description": "Gövde 16.384 baytı aşıyor; /api/support/ask ve Telegram webhook'u için sınır 65.536 bayttır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json gereklidir.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Hız sınırı aşıldı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "Sunucu her zaman 60 döndürür; bu, saatlik kotanın dolduğunu garanti etmez." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/telegram/webhook": { "post": { "tags": [ "Telegram" ], "operationId": "receiveTelegramUpdate", "summary": "Bir Telegram Bot API olayı al", "description": "Yalnızca Telegram gizli üstbilgisini gerektirir, oturum, CSRF veya Origin olmadan. Ek Update alanlarına izin verilir. message ve callback_query'i işler; kişisel eylemler doğrulanmış gönderenin özel sohbetini gerektirir. Diğer güncellemeler atlanır. update_id yinelenenleri kaldırır; devam eden bir güncelleme yeniden deneme için 503 döndürür. Bu bir ödeme sağlayıcısı webhook'u değildir.", "security": [ { "telegramWebhookSecret": [] } ], "requestBody": { "required": true, "description": "Telegram Update, en fazla 65.536 bayt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramUpdate" } } } }, "responses": { "200": { "description": "İşlendi, atlandı veya zaten ele alındı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ], "additionalProperties": false } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "413": { "description": "Gövde 16.384 baytı aşıyor; /api/support/ask ve Telegram webhook'u için sınır 65.536 bayttır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json gereklidir.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Hız sınırı aşıldı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "Sunucu her zaman 60 döndürür; bu, saatlik kotanın dolduğunu garanti etmez." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "502": { "description": "Telegram isteği başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TELEGRAM_UNAVAILABLE", "TELEGRAM_INVALID_RESPONSE", "TELEGRAM_RATE_LIMITED", "TELEGRAM_DELIVERY_FAILED" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/payments": { "post": { "tags": [ "Disabled payments" ], "operationId": "paymentsUnavailable", "summary": "Finansal işlem kullanılamıyor", "description": "503 GATEWAY_NOT_CONNECTED döndürür. Finansal işlemler kullanılamıyor. Gövde işlenmez ve ağ geçidi isteği yapılmaz.", "security": [], "responses": { "503": { "description": "Finansal işlemler kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "GATEWAY_NOT_CONNECTED" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/payouts": { "post": { "tags": [ "Disabled payments" ], "operationId": "payoutsUnavailable", "summary": "Finansal işlem kullanılamıyor", "description": "503 GATEWAY_NOT_CONNECTED döndürür. Finansal işlemler kullanılamıyor. Gövde işlenmez ve ağ geçidi isteği yapılmaz.", "security": [], "responses": { "503": { "description": "Finansal işlemler kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "GATEWAY_NOT_CONNECTED" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/openapi.json": { "get": { "tags": [ "Service" ], "operationId": "getOpenApi", "summary": "Herkese açık makine tarafından okunabilir sözleşme", "description": "Yalnızca okuma. Sırlar, oturumlar, kullanıcı kayıtları veya operasyonel ödeme sağlayıcısı sözleşmesi içermez.", "responses": { "200": { "description": "Bu OpenAPI 3.1 belgesi.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "public, max-age=300" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "openapi", "info", "paths" ], "additionalProperties": true } } } } } } }, "/api/payment-links": { "get": { "tags": [ "Payment links" ], "operationId": "listOwnPaymentLinks", "summary": "Sahip olunan ödeme bağlantılarını listele", "security": [ { "cookieSession": [] } ], "description": "createdAt DESC, id DESC ile sıralanır. Genel bağlantılar cihazlar arasında çalışır; listeleme bir hesap gerektirir.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Önceki yanıttan nextCursor. Hizmet base64 JSON [createdAt,id] kullanır; URLSearchParams üzerinden değiştirilmeden iletin." }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Tarayıcı oturumu için sahip olunan bir mağaza seçin. İlk mağazayı kullanmak için atlayın. API anahtarları bu başlığı yok sayar ve her zaman değişmez mağaza bağlamasını kullanır. all değeri salt okunurdur ve yalnızca gösterge paneli ve fatura listesi uç noktaları tarafından desteklenir." } ], "responses": { "200": { "description": "Sahip olunan ödeme bağlantılarından oluşan bir sayfa.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinksPage" } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } }, "post": { "tags": [ "Payment links" ], "operationId": "createOwnPaymentLink", "summary": "Değişmez koşullarla bir fatura oluştur", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "APP_ORIGIN ile birebir eşleşmelidir. Sec-Fetch-Site: cross-site reddedilir. Sunucu CORS erişimi sağlamaz.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "GET /api/auth/me veya başarılı giriş tamamlamadan gelen geçerli oturum belirteci.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,100}$" }, "description": "Mantıksal istek başına bir anahtar. Aynı kurallı girdiyle tekrar, orijinal kaydı döndürür; aynı anahtarla farklı girdi 409 döndürür." }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Tarayıcı oturumu için sahip olunan bir mağaza seçin. İlk mağazayı kullanmak için atlayın. API anahtarları bu başlığı yok sayar ve her zaman değişmez mağaza bağlamasını kullanır. all değeri salt okunurdur ve yalnızca gösterge paneli ve fatura listesi uç noktaları tarafından desteklenir." } ], "description": "Değişmez bir fatura oluştur ve hemen checkoutUrl al; bu alıcıyı ücretlendirmez. USD: kart/Alipay; RUB: SBP; USDT: kripto. USD kripto uyumluluk için kabul edilir ancak bir USDT faturası olmadan ödenemez. Ücret ve KDV müşteri payları 0'dan 100'e bağımsız tam sayılardır; mevcut canlı kart/Alipay, KDV müşteri=100 ve ücret müşteri=0 destekler. Müşteri toplamı asla sessizce değiştirilmez. En son web sitesi uygulaması yeni bir canlı ücretlendirmeden önce onaylanmalıdır. Fatura oluşturma ve tüccar olayı atomik olarak işlenir.", "requestBody": { "required": true, "description": "JSON nesnesi. En fazla 16.384 bayt. Bilinmeyen alanlar reddedilir.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentLink" } } } }, "responses": { "200": { "description": "Idempotent tekrar; replayed=true.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentLinkResponse" } } } }, "201": { "description": "Fatura oluşturuldu; replayed=false.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentLinkResponse" } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "409": { "description": "Giriş talebi kullanıldı veya iptal edildi, kimlik doğrulanmadı veya bir destek talebi çakışıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "413": { "description": "Gövde 16.384 baytı aşıyor; /api/support/ask ve Telegram webhook'u için sınır 65.536 bayttır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json gereklidir.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Hız sınırı aşıldı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "Sunucu her zaman 60 döndürür; bu, saatlik kotanın dolduğunu garanti etmez." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/payment-links/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^lnk_[0-9a-f-]{36}$" }, "description": "Sahip olunan bağlantı tanımlayıcısı, genel belirteç değil." } ], "get": { "tags": [ "Payment links" ], "operationId": "getOwnPaymentLink", "summary": "Sahip olunan bağlantı ve kaydedilmiş hesaplama", "security": [ { "cookieSession": [] } ], "responses": { "200": { "description": "Başka bir kullanıcının kimliği ve eksik bir kimlik ikisi de 404 döndürür.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkResponse" } } } }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "404": { "description": "Kayıt eksik, genel belirteç geçersiz veya istenen kayıt başka bir kullanıcıya ait.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "parameters": [ { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Tarayıcı oturumu için sahip olunan bir mağaza seçin. İlk mağazayı kullanmak için atlayın. API anahtarları bu başlığı yok sayar ve her zaman değişmez mağaza bağlamasını kullanır. all değeri salt okunurdur ve yalnızca gösterge paneli ve fatura listesi uç noktaları tarafından desteklenir." } ] }, "patch": { "tags": [ "Payment links" ], "operationId": "changePaymentLinkStatus", "summary": "Bir bağlantıyı duraklat, sürdür veya iptal et", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "APP_ORIGIN ile birebir eşleşmelidir. Sec-Fetch-Site: cross-site reddedilir. Sunucu CORS erişimi sağlamaz.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "GET /api/auth/me veya başarılı giriş tamamlamadan gelen geçerli oturum belirteci.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Tarayıcı oturumu için sahip olunan bir mağaza seçin. İlk mağazayı kullanmak için atlayın. API anahtarları bu başlığı yok sayar ve her zaman değişmez mağaza bağlamasını kullanır. all değeri salt okunurdur ve yalnızca gösterge paneli ve fatura listesi uç noktaları tarafından desteklenir." } ], "description": "Yalnızca durumu değiştirir. Güncelleme ve değişmez fatura updated olayı atomik olarak işlenir. Eşzamanlı değişiklikler bir sürüm kontrolü kullanır; LINK_CHANGED üzerinde yenileyin ve yeniden deneyin. cancelled terminaldir, süre sonu asla uzatılmaz ve fiyat, yöntemler, maliyet payları ve açıklama donmuş kalır. Kaydedilmiş durumun tekrarlanması geçerli faturayı döndürür.", "requestBody": { "required": true, "description": "JSON nesnesi. En fazla 16.384 bayt. Bilinmeyen alanlar reddedilir.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "paused", "cancelled" ] } }, "required": [ "status" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Sahip olunan bağlantının geçerli durumu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkResponse" } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "Kayıt eksik, genel belirteç geçersiz veya istenen kayıt başka bir kullanıcıya ait.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "Giriş talebi kullanıldı veya iptal edildi, kimlik doğrulanmadı veya bir destek talebi çakışıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "413": { "description": "Gövde 16.384 baytı aşıyor; /api/support/ask ve Telegram webhook'u için sınır 65.536 bayttır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json gereklidir.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/checkout/{token}": { "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "description": "Ödeme sayfası URL'sinden rastgele genel tanımlayıcı. Yalnızca bu faturaya okuma erişimi verir." } ], "get": { "tags": [ "Checkout" ], "operationId": "getPublicCheckout", "summary": "Müşteri için genel fatura ayrıntıları", "description": "Değişmez genel fatura teklifini ve kalıcı ödeme anlık görüntüsünü oku. method faturanın kaydedilmiş yöntemlerine ait olmalıdır. Hesap gerekmez. Sahip kimliğini, özel meta verileri veya tüccar gelirlerini açığa çıkarmaz. Belirteç yalnızca bu ödeme sayfasına erişim sağlar. availability yapılandırmayı, tahsisi, teknik sınırları ve tüccar onayını yansıtır; ödeme onayı ayrıdır.", "parameters": [ { "name": "method", "in": "query", "schema": { "type": "string", "enum": [ "card", "alipay", "sbp", "crypto" ] }, "description": "Faturanın kaydedilmiş yöntemlerinde mevcut olmalıdır." } ], "responses": { "200": { "description": "Genel fatura ve gönderilmişse mevcut ödeme.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice": { "$ref": "#/components/schemas/CheckoutInvoice" }, "payment": { "oneOf": [ { "$ref": "#/components/schemas/CheckoutPayment" }, { "type": "null" } ] } }, "required": [ "invoice", "payment" ], "additionalProperties": false } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "404": { "description": "Kayıt eksik, genel belirteç geçersiz veya istenen kayıt başka bir kullanıcıya ait.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "429": { "description": "Hız sınırı aşıldı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "Sunucu her zaman 60 döndürür; bu, saatlik kotanın dolduğunu garanti etmez." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/checkout/{token}/pay": { "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "description": "Ödeme sayfası URL'sinden rastgele genel tanımlayıcı. Yalnızca bu faturaya okuma erişimi verir." } ], "post": { "tags": [ "Checkout" ], "operationId": "startCheckoutPayment", "summary": "Fatura ödemesini başlat veya kurtar", "description": "Aynı kaynaktan alıcı işlemi; hesap veya CSRF belirteci gerekmez. Sunucu, ağ geçidi gönderiminden önce bir işlem ve istikrarlı bir kimliksizlik anahtarı ayırır. Tekrar, aynı işlemi kurtarır; kaybolan bir yanıt durum üzerinden çözülmelidir. Ödeme yöntemi gönderimden sonra kilitlenir. Kart verileri, yeni bir ödeme niyetiyle tarayıcıda şifrelenmelidir. SBP/kripto, kayıtlı müşteri toplamını gönderir; kart/Alipay desteklenen değişmez vergi yapılandırmasını kullanır. Yeni ücretlendirmeler onaylanmış bir satıcı başvurusu gerektirir. Mevcut gönderilmiş ödemeler, fatura süresi dolduktan, duraklatıldıktan veya onay değişikliklerinden sonra kurtarılabilir. /v2 veya barındırılan kart yolu kullanılmaz.", "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "APP_ORIGIN ile birebir eşleşmelidir. Sec-Fetch-Site: cross-site reddedilir. Sunucu CORS erişimi sağlamaz.", "schema": { "type": "string", "format": "uri" } } ], "requestBody": { "required": true, "description": "JSON nesnesi. En fazla 16.384 bayt. Bilinmeyen alanlar reddedilir.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartCheckoutPayment" } } } }, "responses": { "200": { "description": "Mevcut işlem kurtarıldı; ikinci bir ödeme yapılmadı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "payment": { "oneOf": [ { "$ref": "#/components/schemas/CheckoutPayment" }, { "type": "null" } ] }, "replayed": { "type": "boolean" } }, "required": [ "payment" ], "additionalProperties": false } } } }, "202": { "description": "İşlem gönderildi; tamamlama eşzamansızdır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "payment": { "oneOf": [ { "$ref": "#/components/schemas/CheckoutPayment" }, { "type": "null" } ] }, "replayed": { "type": "boolean" } }, "required": [ "payment" ], "additionalProperties": false } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "Kayıt eksik, genel belirteç geçersiz veya istenen kayıt başka bir kullanıcıya ait.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "Giriş talebi kullanıldı veya iptal edildi, kimlik doğrulanmadı veya bir destek talebi çakışıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "410": { "description": "Ağ geçidi şifreleme niyeti veya banka meydan okuması süresi doldu. Aynı işlem için yeni bir niyet edinin; değiştirme ödemesi oluşturmayın.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CARD_SESSION_INVALID" ] }, "413": { "description": "Gövde 16.384 baytı aşıyor; /api/support/ask ve Telegram webhook'u için sınır 65.536 bayttır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json gereklidir.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Hız sınırı aşıldı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "Sunucu her zaman 60 döndürür; bu, saatlik kotanın dolduğunu garanti etmez." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "502": { "description": "Ağ geçidi yanıtı kullanılamıyor, hatalı veya doğrulanamıyor. Herhangi bir yeniden denemeden önce mevcut ödeme durumunu okuyun.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "GATEWAY_REQUEST_UNCERTAIN", "GATEWAY_INVALID_RESPONSE" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/v1/payments": { "get": { "tags": [ "Merchant API" ], "operationId": "listOwnPaymentLinksViaPayments", "summary": "Sahip olunan ödeme bağlantılarını listele", "security": [ { "merchantKey": [] } ], "description": "createdAt DESC, id DESC ile sıralanır. Genel bağlantılar cihazlar arasında çalışır; listeleme bir hesap gerektirir.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Önceki yanıttan nextCursor. Hizmet base64 JSON [createdAt,id] kullanır; URLSearchParams üzerinden değiştirilmeden iletin." } ], "responses": { "200": { "description": "Sahip olunan ödeme bağlantılarından oluşan bir sayfa.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinksPage" } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "x-required-scope": "invoices:read" }, "post": { "tags": [ "Merchant API" ], "operationId": "createOwnPaymentLinkViaPayments", "summary": "Değişmez koşullarla bir fatura oluştur", "security": [ { "merchantKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,100}$" }, "description": "Mantıksal istek başına bir anahtar. Aynı kurallı girdiyle tekrar, orijinal kaydı döndürür; aynı anahtarla farklı girdi 409 döndürür." } ], "description": "Değişmez bir fatura oluştur ve hemen checkoutUrl al; bu alıcıyı ücretlendirmez. USD: kart/Alipay; RUB: SBP; USDT: kripto. USD kripto uyumluluk için kabul edilir ancak bir USDT faturası olmadan ödenemez. Ücret ve KDV müşteri payları 0'dan 100'e bağımsız tam sayılardır; mevcut canlı kart/Alipay, KDV müşteri=100 ve ücret müşteri=0 destekler. Müşteri toplamı asla sessizce değiştirilmez. En son web sitesi uygulaması yeni bir canlı ücretlendirmeden önce onaylanmalıdır. Fatura oluşturma ve tüccar olayı atomik olarak işlenir.", "requestBody": { "required": true, "description": "JSON nesnesi. En fazla 16.384 bayt. Bilinmeyen alanlar reddedilir.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentLink" } } } }, "responses": { "200": { "description": "Idempotent tekrar; replayed=true.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentLinkResponse" } } } }, "201": { "description": "Fatura oluşturuldu; replayed=false.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentLinkResponse" } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "409": { "description": "Giriş talebi kullanıldı veya iptal edildi, kimlik doğrulanmadı veya bir destek talebi çakışıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "413": { "description": "Gövde 16.384 baytı aşıyor; /api/support/ask ve Telegram webhook'u için sınır 65.536 bayttır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json gereklidir.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Hız sınırı aşıldı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "Sunucu her zaman 60 döndürür; bu, saatlik kotanın dolduğunu garanti etmez." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "x-required-scope": "invoices:write" } }, "/api/v1/payments/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^lnk_[0-9a-f-]{36}$" }, "description": "Sahip olunan bağlantı tanımlayıcısı, genel belirteç değil." } ], "get": { "tags": [ "Merchant API" ], "operationId": "getOwnPaymentLinkViaPayments", "summary": "Sahip olunan bağlantı ve kaydedilmiş hesaplama", "security": [ { "merchantKey": [] } ], "responses": { "200": { "description": "Başka bir kullanıcının kimliği ve eksik bir kimlik ikisi de 404 döndürür.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkResponse" } } } }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "404": { "description": "Kayıt eksik, genel belirteç geçersiz veya istenen kayıt başka bir kullanıcıya ait.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "parameters": [], "x-required-scope": "invoices:read" }, "patch": { "tags": [ "Merchant API" ], "operationId": "changePaymentLinkStatusViaPayments", "summary": "Bir bağlantıyı duraklat, sürdür veya iptal et", "security": [ { "merchantKey": [] } ], "parameters": [], "description": "Yalnızca durumu değiştirir. Güncelleme ve değişmez fatura updated olayı atomik olarak işlenir. Eşzamanlı değişiklikler bir sürüm kontrolü kullanır; LINK_CHANGED üzerinde yenileyin ve yeniden deneyin. cancelled terminaldir, süre sonu asla uzatılmaz ve fiyat, yöntemler, maliyet payları ve açıklama donmuş kalır. Kaydedilmiş durumun tekrarlanması geçerli faturayı döndürür.", "requestBody": { "required": true, "description": "JSON nesnesi. En fazla 16.384 bayt. Bilinmeyen alanlar reddedilir.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "paused", "cancelled" ] } }, "required": [ "status" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Sahip olunan bağlantının geçerli durumu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkResponse" } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "Kayıt eksik, genel belirteç geçersiz veya istenen kayıt başka bir kullanıcıya ait.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "Giriş talebi kullanıldı veya iptal edildi, kimlik doğrulanmadı veya bir destek talebi çakışıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "413": { "description": "Gövde 16.384 baytı aşıyor; /api/support/ask ve Telegram webhook'u için sınır 65.536 bayttır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json gereklidir.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "x-required-scope": "invoices:write" } }, "/api/v1/payment-links": { "get": { "tags": [ "Merchant API" ], "operationId": "listOwnPaymentLinksViaLinks", "summary": "Sahip olunan ödeme bağlantılarını listele", "security": [ { "merchantKey": [] } ], "description": "createdAt DESC, id DESC ile sıralanır. Genel bağlantılar cihazlar arasında çalışır; listeleme bir hesap gerektirir.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Önceki yanıttan nextCursor. Hizmet base64 JSON [createdAt,id] kullanır; URLSearchParams üzerinden değiştirilmeden iletin." } ], "responses": { "200": { "description": "Sahip olunan ödeme bağlantılarından oluşan bir sayfa.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinksPage" } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "x-required-scope": "invoices:read" }, "post": { "tags": [ "Merchant API" ], "operationId": "createOwnPaymentLinkViaLinks", "summary": "Değişmez koşullarla bir fatura oluştur", "security": [ { "merchantKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,100}$" }, "description": "Mantıksal istek başına bir anahtar. Aynı kurallı girdiyle tekrar, orijinal kaydı döndürür; aynı anahtarla farklı girdi 409 döndürür." } ], "description": "Değişmez bir fatura oluştur ve hemen checkoutUrl al; bu alıcıyı ücretlendirmez. USD: kart/Alipay; RUB: SBP; USDT: kripto. USD kripto uyumluluk için kabul edilir ancak bir USDT faturası olmadan ödenemez. Ücret ve KDV müşteri payları 0'dan 100'e bağımsız tam sayılardır; mevcut canlı kart/Alipay, KDV müşteri=100 ve ücret müşteri=0 destekler. Müşteri toplamı asla sessizce değiştirilmez. En son web sitesi uygulaması yeni bir canlı ücretlendirmeden önce onaylanmalıdır. Fatura oluşturma ve tüccar olayı atomik olarak işlenir.", "requestBody": { "required": true, "description": "JSON nesnesi. En fazla 16.384 bayt. Bilinmeyen alanlar reddedilir.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentLink" } } } }, "responses": { "200": { "description": "Idempotent tekrar; replayed=true.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentLinkResponse" } } } }, "201": { "description": "Fatura oluşturuldu; replayed=false.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentLinkResponse" } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "409": { "description": "Giriş talebi kullanıldı veya iptal edildi, kimlik doğrulanmadı veya bir destek talebi çakışıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "413": { "description": "Gövde 16.384 baytı aşıyor; /api/support/ask ve Telegram webhook'u için sınır 65.536 bayttır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json gereklidir.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Hız sınırı aşıldı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "Sunucu her zaman 60 döndürür; bu, saatlik kotanın dolduğunu garanti etmez." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "x-required-scope": "invoices:write" } }, "/api/v1/payment-links/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^lnk_[0-9a-f-]{36}$" }, "description": "Sahip olunan bağlantı tanımlayıcısı, genel belirteç değil." } ], "get": { "tags": [ "Merchant API" ], "operationId": "getOwnPaymentLinkViaLinks", "summary": "Sahip olunan bağlantı ve kaydedilmiş hesaplama", "security": [ { "merchantKey": [] } ], "responses": { "200": { "description": "Başka bir kullanıcının kimliği ve eksik bir kimlik ikisi de 404 döndürür.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkResponse" } } } }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "404": { "description": "Kayıt eksik, genel belirteç geçersiz veya istenen kayıt başka bir kullanıcıya ait.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "parameters": [], "x-required-scope": "invoices:read" }, "patch": { "tags": [ "Merchant API" ], "operationId": "changePaymentLinkStatusViaLinks", "summary": "Bir bağlantıyı duraklat, sürdür veya iptal et", "security": [ { "merchantKey": [] } ], "parameters": [], "description": "Yalnızca durumu değiştirir. Güncelleme ve değişmez fatura updated olayı atomik olarak işlenir. Eşzamanlı değişiklikler bir sürüm kontrolü kullanır; LINK_CHANGED üzerinde yenileyin ve yeniden deneyin. cancelled terminaldir, süre sonu asla uzatılmaz ve fiyat, yöntemler, maliyet payları ve açıklama donmuş kalır. Kaydedilmiş durumun tekrarlanması geçerli faturayı döndürür.", "requestBody": { "required": true, "description": "JSON nesnesi. En fazla 16.384 bayt. Bilinmeyen alanlar reddedilir.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "paused", "cancelled" ] } }, "required": [ "status" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Sahip olunan bağlantının geçerli durumu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkResponse" } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "Kayıt eksik, genel belirteç geçersiz veya istenen kayıt başka bir kullanıcıya ait.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "Giriş talebi kullanıldı veya iptal edildi, kimlik doğrulanmadı veya bir destek talebi çakışıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "413": { "description": "Gövde 16.384 baytı aşıyor; /api/support/ask ve Telegram webhook'u için sınır 65.536 bayttır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json gereklidir.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "x-required-scope": "invoices:write" } }, "/api/api-keys": { "get": { "tags": [ "Merchant API" ], "operationId": "listMerchantKeys", "summary": "Kendi anahtar meta verilerini listele", "security": [ { "cookieSession": [] } ], "responses": { "200": { "description": "Sırlar ve sır karmaları atlanır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantKey" } } }, "required": [ "keys" ], "additionalProperties": false } } } }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "parameters": [ { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Tarayıcı oturumu için sahip olunan bir mağaza seçin. İlk mağazayı kullanmak için atlayın. API anahtarları bu başlığı yok sayar ve her zaman değişmez mağaza bağlamasını kullanır. all değeri salt okunurdur ve yalnızca gösterge paneli ve fatura listesi uç noktaları tarafından desteklenir." } ] }, "post": { "tags": [ "Merchant API" ], "operationId": "createMerchantKey", "summary": "Kapsamlı bir anahtar oluştur; sırrını bir kez göster", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "APP_ORIGIN ile birebir eşleşmelidir. Sec-Fetch-Site: cross-site reddedilir. Sunucu CORS erişimi sağlamaz.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "GET /api/auth/me veya başarılı giriş tamamlamadan gelen geçerli oturum belirteci.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Tarayıcı oturumu için sahip olunan bir mağaza seçin. İlk mağazayı kullanmak için atlayın. API anahtarları bu başlığı yok sayar ve her zaman değişmez mağaza bağlamasını kullanır. all değeri salt okunurdur ve yalnızca gösterge paneli ve fatura listesi uç noktaları tarafından desteklenir." } ], "description": "En fazla 10 etkin anahtar. Saatte kullanıcı başına en fazla 5 oluşturma. Anahtarların süresi dolar, iptal edilebilir ve anahtar başına dakikada 90 API isteğiyle sınırlandırılmıştır.", "requestBody": { "required": true, "description": "JSON nesnesi. En fazla 16.384 bayt. Bilinmeyen alanlar reddedilir.", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "scopes": { "type": "array", "minItems": 1, "maxItems": 3, "uniqueItems": true, "items": { "type": "string", "enum": [ "invoices:read", "invoices:write", "events:read" ] } }, "expiresInDays": { "type": "integer", "minimum": 1, "maximum": 365, "default": 90 } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Sırrı sunucunda güvenli bir şekilde sakla.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/MerchantKey" }, "secret": { "type": "string", "pattern": "^kv_live_[A-Za-z0-9_-]{43}$" } }, "required": [ "key", "secret" ], "additionalProperties": false } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "409": { "description": "Giriş talebi kullanıldı veya iptal edildi, kimlik doğrulanmadı veya bir destek talebi çakışıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "429": { "description": "Hız sınırı aşıldı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "Sunucu her zaman 60 döndürür; bu, saatlik kotanın dolduğunu garanti etmez." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/api-keys/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^key_[0-9a-f-]{36}$" } } ], "delete": { "tags": [ "Merchant API" ], "operationId": "revokeMerchantKey", "summary": "Kendi anahtarını iptal et", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "APP_ORIGIN ile birebir eşleşmelidir. Sec-Fetch-Site: cross-site reddedilir. Sunucu CORS erişimi sağlamaz.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "GET /api/auth/me veya başarılı giriş tamamlamadan gelen geçerli oturum belirteci.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Tarayıcı oturumu için sahip olunan bir mağaza seçin. İlk mağazayı kullanmak için atlayın. API anahtarları bu başlığı yok sayar ve her zaman değişmez mağaza bağlamasını kullanır. all değeri salt okunurdur ve yalnızca gösterge paneli ve fatura listesi uç noktaları tarafından desteklenir." } ], "responses": { "200": { "description": "Anahtarın gelecekteki kullanımları reddedilir.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "const": true } }, "required": [ "revoked" ], "additionalProperties": false } } } }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "Kayıt eksik, genel belirteç geçersiz veya istenen kayıt başka bir kullanıcıya ait.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/events": { "get": { "tags": [ "Merchant API" ], "operationId": "listOwnEvents", "summary": "Kendi değişmez olay geçmişini oku", "security": [ { "cookieSession": [] } ], "parameters": [ { "name": "before", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." }, "description": "Eski özel zaman damgası sınırı. İmleçle birleştirilemez. Kayıpsız sayfalama için nextCursor kullanın." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Önceki sayfa tarafından döndürülen opak nextCursor. [createdAt,id] kodlar ve tek zaman damgasını paylaşan olayları korur." }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Tarayıcı oturumu için sahip olunan bir mağaza seçin. İlk mağazayı kullanmak için atlayın. API anahtarları bu başlığı yok sayar ve her zaman değişmez mağaza bağlamasını kullanır. all değeri salt okunurdur ve yalnızca gösterge paneli ve fatura listesi uç noktaları tarafından desteklenir." } ], "responses": { "200": { "description": "En yeni önce; en fazla 50 olay. null olana kadar nextCursor'ı takip edin.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/MerchantEvent" } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "events", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/v1/events": { "get": { "tags": [ "Merchant API" ], "operationId": "listMerchantEventsWithKey", "summary": "Kendi değişmez olay geçmişini oku", "security": [ { "merchantKey": [] } ], "parameters": [ { "name": "before", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." }, "description": "Eski özel zaman damgası sınırı. İmleçle birleştirilemez. Kayıpsız sayfalama için nextCursor kullanın." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Önceki sayfa tarafından döndürülen opak nextCursor. [createdAt,id] kodlar ve tek zaman damgasını paylaşan olayları korur." } ], "responses": { "200": { "description": "En yeni önce; en fazla 50 olay. null olana kadar nextCursor'ı takip edin.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/MerchantEvent" } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "events", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "x-required-scope": "events:read" } }, "/api/webhooks": { "get": { "tags": [ "Webhooks" ], "operationId": "listWebhookEndpoints", "summary": "Uç noktalarını ve son 30 teslimatı listele", "security": [ { "cookieSession": [] } ], "responses": { "200": { "description": "İmzalama sırları döndürülmez.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "available": { "type": "boolean" }, "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "invoice.created", "invoice.updated", "payment.succeeded", "payment.failed", "payment.refunded", "payment.partially_refunded", "payment.disputed", "payment.review_required" ] } } }, "required": [ "endpoints", "deliveries", "available", "eventTypes" ], "additionalProperties": false } } } }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "404": { "description": "Kayıt eksik, genel belirteç geçersiz veya istenen kayıt başka bir kullanıcıya ait.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "parameters": [ { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Tarayıcı oturumu için sahip olunan bir mağaza seçin. İlk mağazayı kullanmak için atlayın. API anahtarları bu başlığı yok sayar ve her zaman değişmez mağaza bağlamasını kullanır. all değeri salt okunurdur ve yalnızca gösterge paneli ve fatura listesi uç noktaları tarafından desteklenir." } ] }, "post": { "tags": [ "Webhooks" ], "operationId": "createWebhookEndpoint", "summary": "Genel bir HTTPS hedefi kaydet", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "APP_ORIGIN ile birebir eşleşmelidir. Sec-Fetch-Site: cross-site reddedilir. Sunucu CORS erişimi sağlamaz.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "GET /api/auth/me veya başarılı giriş tamamlamadan gelen geçerli oturum belirteci.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Tarayıcı oturumu için sahip olunan bir mağaza seçin. İlk mağazayı kullanmak için atlayın. API anahtarları bu başlığı yok sayar ve her zaman değişmez mağaza bağlamasını kullanır. all değeri salt okunurdur ve yalnızca gösterge paneli ve fatura listesi uç noktaları tarafından desteklenir." } ], "description": "En fazla 5 uç noktası ve saatte kullanıcı başına 6 oluşturma. Yalnızca genel HTTPS alan adları; kimlik bilgisi, IP değişmezleri veya özel bağlantı noktaları yok. Yeni oluşturulan bir uç noktası, meydan okuması başarılı olana kadar canlı teslimat almaz.", "requestBody": { "required": true, "description": "JSON nesnesi. En fazla 16.384 bayt. Bilinmeyen alanlar reddedilir.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "description": { "type": "string", "maxLength": 120 }, "events": { "type": "array", "minItems": 1, "maxItems": 8, "uniqueItems": true, "items": { "type": "string", "enum": [ "invoice.created", "invoice.updated", "payment.succeeded", "payment.failed", "payment.refunded", "payment.partially_refunded", "payment.disputed", "payment.review_required" ] } } }, "required": [ "url" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Tek seferlik imzalama sırrını kaydet.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoint": { "$ref": "#/components/schemas/WebhookEndpoint" }, "secret": { "type": "string", "pattern": "^whsec_[A-Za-z0-9_-]{43}$", "description": "Yalnızca oluşturma/döndürmede gösterilir. Sunucu tarafında şifrelenmiş olarak saklanır." } }, "required": [ "endpoint", "secret" ], "additionalProperties": false } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "409": { "description": "Giriş talebi kullanıldı veya iptal edildi, kimlik doğrulanmadı veya bir destek talebi çakışıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "429": { "description": "Hız sınırı aşıldı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "Sunucu her zaman 60 döndürür; bu, saatlik kotanın dolduğunu garanti etmez." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/webhooks/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wh_[0-9a-f-]{36}$" } } ], "get": { "tags": [ "Webhooks" ], "operationId": "getWebhookEndpoint", "summary": "Uç noktalarını ve son 30 teslimatı listele", "security": [ { "cookieSession": [] } ], "responses": { "200": { "description": "İmzalama sırları döndürülmez.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "available": { "type": "boolean" }, "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "invoice.created", "invoice.updated", "payment.succeeded", "payment.failed", "payment.refunded", "payment.partially_refunded", "payment.disputed", "payment.review_required" ] } } }, "required": [ "endpoints", "deliveries", "available", "eventTypes" ], "additionalProperties": false } } } }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "404": { "description": "Kayıt eksik, genel belirteç geçersiz veya istenen kayıt başka bir kullanıcıya ait.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "parameters": [ { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Tarayıcı oturumu için sahip olunan bir mağaza seçin. İlk mağazayı kullanmak için atlayın. API anahtarları bu başlığı yok sayar ve her zaman değişmez mağaza bağlamasını kullanır. all değeri salt okunurdur ve yalnızca gösterge paneli ve fatura listesi uç noktaları tarafından desteklenir." } ] }, "patch": { "tags": [ "Webhooks" ], "operationId": "setWebhookStatus", "summary": "Doğrulanmış bir uç noktasını duraklat veya sürdür", "description": "Duraklatılmış doğrulanmış uç noktaları uygun olayları kuyrukta tutar; sürdürme, vadesi gelen teslimatları işler.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "APP_ORIGIN ile birebir eşleşmelidir. Sec-Fetch-Site: cross-site reddedilir. Sunucu CORS erişimi sağlamaz.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "GET /api/auth/me veya başarılı giriş tamamlamadan gelen geçerli oturum belirteci.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Tarayıcı oturumu için sahip olunan bir mağaza seçin. İlk mağazayı kullanmak için atlayın. API anahtarları bu başlığı yok sayar ve her zaman değişmez mağaza bağlamasını kullanır. all değeri salt okunurdur ve yalnızca gösterge paneli ve fatura listesi uç noktaları tarafından desteklenir." } ], "requestBody": { "required": true, "description": "JSON nesnesi. En fazla 16.384 bayt. Bilinmeyen alanlar reddedilir.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "paused" ] } }, "required": [ "status" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Durum kaydedildi.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "updated": { "const": true } }, "required": [ "updated" ], "additionalProperties": false } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "Kayıt eksik, genel belirteç geçersiz veya istenen kayıt başka bir kullanıcıya ait.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "Giriş talebi kullanıldı veya iptal edildi, kimlik doğrulanmadı veya bir destek talebi çakışıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } }, "delete": { "tags": [ "Webhooks" ], "operationId": "deleteWebhookEndpoint", "summary": "Uç noktasını kaldır ve teslim edilmemiş işleri iptal et", "description": "Bekleyen, başarısız ve kiralanmış işleri iptal eder. Ağ üzerinden zaten gönderilmiş bir istek geri çağrılamaz.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "APP_ORIGIN ile birebir eşleşmelidir. Sec-Fetch-Site: cross-site reddedilir. Sunucu CORS erişimi sağlamaz.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "GET /api/auth/me veya başarılı giriş tamamlamadan gelen geçerli oturum belirteci.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Tarayıcı oturumu için sahip olunan bir mağaza seçin. İlk mağazayı kullanmak için atlayın. API anahtarları bu başlığı yok sayar ve her zaman değişmez mağaza bağlamasını kullanır. all değeri salt okunurdur ve yalnızca gösterge paneli ve fatura listesi uç noktaları tarafından desteklenir." } ], "responses": { "200": { "description": "Uç noktası kaldırıldı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "const": true } }, "required": [ "deleted" ], "additionalProperties": false } } } }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "Kayıt eksik, genel belirteç geçersiz veya istenen kayıt başka bir kullanıcıya ait.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/webhooks/{id}/verify": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wh_[0-9a-f-]{36}$" } } ], "post": { "tags": [ "Webhooks" ], "operationId": "verifyWebhookEndpoint", "summary": "İmzalı bir uç noktası doğrulama meydan okuması gönder", "description": "Saatte kullanıcı başına en fazla 5 doğrulama denemesi. Sunucun, Kevmi-Signature değerini doğrulamalı ve 2xx JSON {\"challenge\":\"\"} döndürmelidir. İstek zaman aşımı: 8 saniye; yanıt sınırı: 8192 bayt. Yönlendirmeler izlenmez. Doğrulama, uç noktasını etkinleştirir.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "APP_ORIGIN ile birebir eşleşmelidir. Sec-Fetch-Site: cross-site reddedilir. Sunucu CORS erişimi sağlamaz.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "GET /api/auth/me veya başarılı giriş tamamlamadan gelen geçerli oturum belirteci.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Tarayıcı oturumu için sahip olunan bir mağaza seçin. İlk mağazayı kullanmak için atlayın. API anahtarları bu başlığı yok sayar ve her zaman değişmez mağaza bağlamasını kullanır. all değeri salt okunurdur ve yalnızca gösterge paneli ve fatura listesi uç noktaları tarafından desteklenir." } ], "requestBody": { "required": true, "description": "JSON nesnesi. En fazla 16.384 bayt. Bilinmeyen alanlar reddedilir.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyObject" } } } }, "responses": { "200": { "description": "Doğrulanmış ve etkin.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "const": true }, "endpoint": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "required": [ "verified", "endpoint" ], "additionalProperties": false } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "Kayıt eksik, genel belirteç geçersiz veya istenen kayıt başka bir kullanıcıya ait.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "Giriş talebi kullanıldı veya iptal edildi, kimlik doğrulanmadı veya bir destek talebi çakışıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "422": { "description": "Hedef doğrulanamadı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "WEBHOOK_UNREACHABLE", "WEBHOOK_VERIFICATION_FAILED" ] }, "429": { "description": "Hız sınırı aşıldı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "Sunucu her zaman 60 döndürür; bu, saatlik kotanın dolduğunu garanti etmez." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/webhooks/{id}/rotate": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wh_[0-9a-f-]{36}$" } } ], "post": { "tags": [ "Webhooks" ], "operationId": "rotateWebhookSecret", "summary": "İmzalama sırrını değiştir ve tekrar doğrulama iste", "description": "Saatte kullanıcı başına en fazla 3 döndürme. Sunucunu güncelle ve uç noktasını tekrar doğrula. Zaten uçuşta olan bir istek hâlâ önceki imzayı taşıyabilir.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "APP_ORIGIN ile birebir eşleşmelidir. Sec-Fetch-Site: cross-site reddedilir. Sunucu CORS erişimi sağlamaz.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "GET /api/auth/me veya başarılı giriş tamamlamadan gelen geçerli oturum belirteci.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Tarayıcı oturumu için sahip olunan bir mağaza seçin. İlk mağazayı kullanmak için atlayın. API anahtarları bu başlığı yok sayar ve her zaman değişmez mağaza bağlamasını kullanır. all değeri salt okunurdur ve yalnızca gösterge paneli ve fatura listesi uç noktaları tarafından desteklenir." } ], "requestBody": { "required": true, "description": "JSON nesnesi. En fazla 16.384 bayt. Bilinmeyen alanlar reddedilir.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyObject" } } } }, "responses": { "200": { "description": "Yeni sır bir kez gösterilir.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": "string", "pattern": "^whsec_[A-Za-z0-9_-]{43}$", "description": "Yalnızca oluşturma/döndürmede gösterilir. Sunucu tarafında şifrelenmiş olarak saklanır." }, "requiresVerification": { "const": true } }, "required": [ "secret", "requiresVerification" ], "additionalProperties": false } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "Kayıt eksik, genel belirteç geçersiz veya istenen kayıt başka bir kullanıcıya ait.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "Giriş talebi kullanıldı veya iptal edildi, kimlik doğrulanmadı veya bir destek talebi çakışıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "429": { "description": "Hız sınırı aşıldı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "Sunucu her zaman 60 döndürür; bu, saatlik kotanın dolduğunu garanti etmez." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/webhooks/{id}/deliveries/{deliveryId}/retry": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wh_[0-9a-f-]{36}$" } }, { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^del_[a-f0-9]{40}$" } } ], "post": { "tags": [ "Webhooks" ], "operationId": "retryWebhookDelivery", "summary": "Etkin bir uç noktasına başarısız bir teslimatı yeniden dene", "description": "Olay kimliğini ve yükünü korur; yeni bir zaman damgası ve imza üretir. Her otomatik teslimat döngüsü, süresi dolmuş kiralamalar dahil en fazla 6 deneme yapar; 1d, 5d, 30d, 2s ve 12s gecikmelerle. Teslimat en az bir kezdir; olay kimliklerini sunucunda tekilleştir.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "APP_ORIGIN ile birebir eşleşmelidir. Sec-Fetch-Site: cross-site reddedilir. Sunucu CORS erişimi sağlamaz.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "GET /api/auth/me veya başarılı giriş tamamlamadan gelen geçerli oturum belirteci.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Tarayıcı oturumu için sahip olunan bir mağaza seçin. İlk mağazayı kullanmak için atlayın. API anahtarları bu başlığı yok sayar ve her zaman değişmez mağaza bağlamasını kullanır. all değeri salt okunurdur ve yalnızca gösterge paneli ve fatura listesi uç noktaları tarafından desteklenir." } ], "requestBody": { "required": true, "description": "JSON nesnesi. En fazla 16.384 bayt. Bilinmeyen alanlar reddedilir.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyObject" } } } }, "responses": { "202": { "description": "Yeniden deneme zamanlandı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "queued": { "const": true } }, "required": [ "queued" ], "additionalProperties": false } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "Kayıt eksik, genel belirteç geçersiz veya istenen kayıt başka bir kullanıcıya ait.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "Giriş talebi kullanıldı veya iptal edildi, kimlik doğrulanmadı veya bir destek talebi çakışıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "429": { "description": "Hız sınırı aşıldı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "Sunucu her zaman 60 döndürür; bu, saatlik kotanın dolduğunu garanti etmez." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/applications": { "get": { "tags": [ "Applications" ], "operationId": "listOwnApplications", "summary": "En fazla 30 kendi uygulamanı listele", "security": [ { "cookieSession": [] } ], "parameters": [ { "name": "X-Kevmi-Locale", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "ru", "en", "es", "de", "fr", "pt", "tr", "kk" ] }, "description": "İzleme URL'si ve sistem mesajı dili. Desteklenen bir değer olmadan, aynı kaynaktan yönlendiren ve tarayıcı dili dikkate alınır; geri dönüş İngilizcedir." }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Tarayıcı oturumu için sahip olunan bir mağaza seçin. İlk mağazayı kullanmak için atlayın. API anahtarları bu başlığı yok sayar ve her zaman değişmez mağaza bağlamasını kullanır. all değeri salt okunurdur ve yalnızca gösterge paneli ve fatura listesi uç noktaları tarafından desteklenir." } ], "responses": { "200": { "description": "En yeni önce.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "applications": { "type": "array", "maxItems": 30, "items": { "$ref": "#/components/schemas/Application" } } }, "required": [ "applications" ], "additionalProperties": false } } } }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } }, "post": { "tags": [ "Applications" ], "operationId": "submitWebsiteApplication", "summary": "Web sitesi bilgilerini gönder ve bir izleme URL'si al", "description": "Onaylanmış Telegram girişi gerektirir. Günde kullanıcı başına en fazla 5 yeni gönderim. Kimliksiz tekrar oynatma 200 döndürür. Sunucu gerçek kalıcı aşamaları ilerletir; kullanılamayan veya riskli otomatik sonuçlar insan incelemesi gerektirir. Onay, ödeme ağ geçidini yapılandırmaz. Sahiplik ve durum, başvuru sahibi tarafından sağlanamaz.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "APP_ORIGIN ile birebir eşleşmelidir. Sec-Fetch-Site: cross-site reddedilir. Sunucu CORS erişimi sağlamaz.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "GET /api/auth/me veya başarılı giriş tamamlamadan gelen geçerli oturum belirteci.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,100}$" }, "description": "Mantıksal istek başına bir anahtar. Aynı kurallı girdiyle tekrar, orijinal kaydı döndürür; aynı anahtarla farklı girdi 409 döndürür." }, { "name": "X-Kevmi-Locale", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "ru", "en", "es", "de", "fr", "pt", "tr", "kk" ] }, "description": "İzleme URL'si ve sistem mesajı dili. Desteklenen bir değer olmadan, aynı kaynaktan yönlendiren ve tarayıcı dili dikkate alınır; geri dönüş İngilizcedir." }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Tarayıcı oturumu için sahip olunan bir mağaza seçin. İlk mağazayı kullanmak için atlayın. API anahtarları bu başlığı yok sayar ve her zaman değişmez mağaza bağlamasını kullanır. all değeri salt okunurdur ve yalnızca gösterge paneli ve fatura listesi uç noktaları tarafından desteklenir." } ], "requestBody": { "required": true, "description": "JSON nesnesi. En fazla 16.384 bayt. Bilinmeyen alanlar reddedilir.", "content": { "application/json": { "schema": { "type": "object", "properties": { "websiteUrl": { "type": "string", "format": "uri", "maxLength": 2048, "description": "Kimlik bilgisi, sorgu parametresi, IP değişmezi veya özel bağlantı noktası olmayan genel HTTPS alan adı. Bir parça, normalleştirme sırasında kaldırılır." }, "businessName": { "type": "string", "minLength": 1, "maxLength": 100 }, "businessType": { "type": "string", "enum": [ "digital_goods", "software", "services", "physical_goods", "education", "other" ] }, "description": { "type": "string", "minLength": 40, "maxLength": 3000 }, "contactTelegram": { "type": "string", "description": "Bir harfle başlayan, ardından harfler/rakamlar/alt çizgiler gelen 5–32 karakterli Telegram kullanıcı adı. İsteğe bağlı @ veya https://t.me/ öneki; çevresindeki boşluklar kırpılır. @username olarak saklanır." }, "consent": { "type": "boolean", "const": true } }, "required": [ "websiteUrl", "businessName", "businessType", "description", "contactTelegram", "consent" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Mevcut gönderim.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "application": { "$ref": "#/components/schemas/Application" }, "url": { "type": "string", "format": "uri" }, "replayed": { "type": "boolean" } }, "required": [ "application", "url", "replayed" ], "additionalProperties": false } } } }, "202": { "description": "Kabul edildi; işleme sunucuda devam ediyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "application": { "$ref": "#/components/schemas/Application" }, "url": { "type": "string", "format": "uri" }, "replayed": { "type": "boolean" } }, "required": [ "application", "url", "replayed" ], "additionalProperties": false } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "409": { "description": "Giriş talebi kullanıldı veya iptal edildi, kimlik doğrulanmadı veya bir destek talebi çakışıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "429": { "description": "Hız sınırı aşıldı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "Sunucu her zaman 60 döndürür; bu, saatlik kotanın dolduğunu garanti etmez." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/applications/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^app_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } } ], "get": { "tags": [ "Applications" ], "operationId": "getOwnApplication", "summary": "Kendi inceleme aşamalarını ve olay geçmişini oku", "security": [ { "cookieSession": [] } ], "parameters": [ { "name": "X-Kevmi-Locale", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "ru", "en", "es", "de", "fr", "pt", "tr", "kk" ] }, "description": "İzleme URL'si ve sistem mesajı dili. Desteklenen bir değer olmadan, aynı kaynaktan yönlendiren ve tarayıcı dili dikkate alınır; geri dönüş İngilizcedir." }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Tarayıcı oturumu için sahip olunan bir mağaza seçin. İlk mağazayı kullanmak için atlayın. API anahtarları bu başlığı yok sayar ve her zaman değişmez mağaza bağlamasını kullanır. all değeri salt okunurdur ve yalnızca gösterge paneli ve fatura listesi uç noktaları tarafından desteklenir." } ], "responses": { "200": { "description": "Özel başvuru sahibi projeksiyonu. Kanıt ve model çıktısı açığa çıkarılmaz.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "application": { "$ref": "#/components/schemas/Application" }, "events": { "type": "array", "maxItems": 40, "items": { "$ref": "#/components/schemas/ApplicationEvent" } } }, "required": [ "application", "events" ], "additionalProperties": false } } } }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "404": { "description": "Kayıt eksik, genel belirteç geçersiz veya istenen kayıt başka bir kullanıcıya ait.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/applications/{id}/resume": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^app_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } } ], "post": { "tags": [ "Applications" ], "operationId": "resumeApplicationJob", "summary": "Uygun bir arka plan aşamasını sürdür", "description": "İncelemeyi atlayamaz veya bir aşamayı onaylayamaz. Bir sunucu kiralaması yinelenen işi önler. İnceleme gerektiren ve son başvurular değişmeden kalır. Dakikada kullanıcı başına en fazla 30 işleme-devam isteği.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "APP_ORIGIN ile birebir eşleşmelidir. Sec-Fetch-Site: cross-site reddedilir. Sunucu CORS erişimi sağlamaz.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "GET /api/auth/me veya başarılı giriş tamamlamadan gelen geçerli oturum belirteci.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "X-Kevmi-Locale", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "ru", "en", "es", "de", "fr", "pt", "tr", "kk" ] }, "description": "İzleme URL'si ve sistem mesajı dili. Desteklenen bir değer olmadan, aynı kaynaktan yönlendiren ve tarayıcı dili dikkate alınır; geri dönüş İngilizcedir." }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Tarayıcı oturumu için sahip olunan bir mağaza seçin. İlk mağazayı kullanmak için atlayın. API anahtarları bu başlığı yok sayar ve her zaman değişmez mağaza bağlamasını kullanır. all değeri salt okunurdur ve yalnızca gösterge paneli ve fatura listesi uç noktaları tarafından desteklenir." } ], "requestBody": { "required": true, "description": "JSON nesnesi. En fazla 16.384 bayt. Bilinmeyen alanlar reddedilir.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyObject" } } } }, "responses": { "200": { "description": "İşleme gerekmez.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "application": { "$ref": "#/components/schemas/Application" } }, "required": [ "application" ], "additionalProperties": false } } } }, "202": { "description": "İşleme zamanlandı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "application": { "$ref": "#/components/schemas/Application" }, "scheduled": { "type": "boolean", "const": true } }, "required": [ "application", "scheduled" ], "additionalProperties": false } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "Kayıt eksik, genel belirteç geçersiz veya istenen kayıt başka bir kullanıcıya ait.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "429": { "description": "Hız sınırı aşıldı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "Sunucu her zaman 60 döndürür; bu, saatlik kotanın dolduğunu garanti etmez." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/moderation/applications": { "get": { "tags": [ "Moderation" ], "operationId": "listModerationApplications", "summary": "Denetim için en fazla 100 başvuruyu listele", "description": "Doğrulanmış Telegram kimliğinin MODERATOR_TELEGRAM_IDS içinde olmasını gerektirir. Tüm durumları içerir; önce needs_review, sonra processing, ardından son durumlar sıralanır; bir grup içinde en yeni güncellemeler önce.", "security": [ { "cookieSession": [] } ], "responses": { "200": { "description": "Moderatör kuyruğu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "applications": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/Application" } } }, "required": [ "applications" ], "additionalProperties": false } } } }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/moderation/applications/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^app_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } } ], "get": { "tags": [ "Moderation" ], "operationId": "getModerationApplication", "summary": "İnceleme kanıtını ve aşama geçmişini oku", "security": [ { "cookieSession": [] } ], "responses": { "200": { "description": "Özel moderatör kanıtı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "application": { "$ref": "#/components/schemas/Application" }, "events": { "type": "array", "maxItems": 40, "items": { "$ref": "#/components/schemas/ApplicationEvent" } }, "evidence": { "type": "object", "additionalProperties": true } }, "required": [ "application", "events", "evidence" ], "additionalProperties": false } } } }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "Kayıt eksik, genel belirteç geçersiz veya istenen kayıt başka bir kullanıcıya ait.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/moderation/applications/{id}/decision": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^app_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } } ], "post": { "tags": [ "Moderation" ], "operationId": "decideApplicationStage", "summary": "Mevcut inceleme aşamasını onayla veya genel bir gerekçeyle reddet", "description": "Yapılandırılmış bir moderatör gerektirir; kullanıcı başına en fazla 30 karar/dakika. expectedVersion atomik olarak karşılaştırılır. Yalnızca mevcut needs_review aşaması onaylanabilir; nihai başvurular sessizce yeniden açılamaz. Reddetme, düzenlenebilir bir genel gerekçe gerektirir. Karar, aşama geçmişi ve etkinleştirilmiş başvuru bildirimi birlikte kaydedilir.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "APP_ORIGIN ile birebir eşleşmelidir. Sec-Fetch-Site: cross-site reddedilir. Sunucu CORS erişimi sağlamaz.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "GET /api/auth/me veya başarılı giriş tamamlamadan gelen geçerli oturum belirteci.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "requestBody": { "required": true, "description": "JSON nesnesi. En fazla 16.384 bayt. Bilinmeyen alanlar reddedilir.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "expectedVersion": { "type": "integer", "minimum": 1 }, "action": { "type": "string", "const": "approve_step" }, "reason": { "type": "string", "maxLength": 0 } }, "required": [ "expectedVersion", "action" ], "additionalProperties": false }, { "type": "object", "properties": { "expectedVersion": { "type": "integer", "minimum": 1 }, "action": { "type": "string", "const": "reject" }, "reason": { "type": "string", "minLength": 10, "maxLength": 1500 } }, "required": [ "expectedVersion", "action", "reason" ], "additionalProperties": false } ] } } } }, "responses": { "200": { "description": "Karar kaydedildi.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "application": { "$ref": "#/components/schemas/Application" } }, "required": [ "application" ], "additionalProperties": false } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "Kayıt eksik, genel belirteç geçersiz veya istenen kayıt başka bir kullanıcıya ait.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "Giriş talebi kullanıldı veya iptal edildi, kimlik doğrulanmadı veya bir destek talebi çakışıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "429": { "description": "Hız sınırı aşıldı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "Sunucu her zaman 60 döndürür; bu, saatlik kotanın dolduğunu garanti etmez." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/gateway/webhook": { "post": { "tags": [ "Gateway events" ], "operationId": "receiveGatewayEvent", "summary": "İmzalı kaynak-yerel ağ geçidi olaylarını al", "description": "Production accepts only signed native v3 events. The retired normalized success format is disabled in production, including when explicitly requested. A valid event triggers a fresh authenticated provider read; the event body never confirms a payment.", "security": [ { "nativeGatewaySignature": [] } ], "parameters": [ { "name": "X-Gateway-Timestamp", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{10}$" }, "description": "Yerel v3 olayları için gereklidir." }, { "name": "X-Gateway-Event-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Yerel v3 için gereklidir; body.id ile eşleşmelidir." } ], "requestBody": { "required": true, "description": "Tam imzalı JSON gövdesi; yerel v3 sınırı: 524288 bayt. İmza doğrulamasından önce ayrıştırıp yeniden serileştirmeyin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeGatewayEvent" } } } }, "responses": { "200": { "description": "Alındı, yinelenmiş veya güvenle yok sayıldı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "received": { "type": "boolean", "const": true }, "replayed": { "type": "boolean" }, "ignored": { "type": "boolean" }, "applied": { "type": "boolean" } }, "required": [ "received" ], "additionalProperties": false } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Ağ geçidi imzası eksik, geçersiz veya kabul edilen zaman penceresinin dışında.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_GATEWAY_SIGNATURE", "INVALID_SIGNATURE", "WEBHOOK_UNAUTHORIZED" ] }, "404": { "description": "Kayıt eksik, genel belirteç geçersiz veya istenen kayıt başka bir kullanıcıya ait.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "Bir olay kimliği değiştirilmiş içerikle yeniden kullanıldı veya bir ödeme kimliği kayıtlı fatura bağlamasıyla çakışıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "GATEWAY_EVENT_CONFLICT", "PAYMENT_ID_CONFLICT" ] }, "413": { "description": "Gövde 16.384 baytı aşıyor; /api/support/ask ve Telegram webhook'u için sınır 65.536 bayttır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json gereklidir.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Ağ geçidi meşgul; webhook teslimatını aynı olay kimliğiyle yeniden deneyin.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "GATEWAY_BUSY" ] }, "502": { "description": "Ağ geçidi yanıtı kullanılamıyor, hatalı veya doğrulanamıyor. Herhangi bir yeniden denemeden önce mevcut ödeme durumunu okuyun.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "GATEWAY_REQUEST_UNCERTAIN", "GATEWAY_INVALID_RESPONSE" ] }, "503": { "description": "Ağ geçidi yapılandırması veya imzalama sırrı eksik.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "GATEWAY_NOT_CONNECTED", "DATABASE_NOT_CONFIGURED" ] } } } }, "/api/jobs/dispatch": { "post": { "tags": [ "Service" ], "operationId": "dispatchBackgroundJobs", "summary": "Vadesi gelen teslimat ve başvuru işlerini çalıştır", "description": "Sunucu zamanlayıcı giriş noktası. JOBS_SECRET gerektirir, bir tarayıcı oturumu veya satıcı anahtarı değil. İş kimliklerini veya rastgele giden URL'leri kabul etmez.", "security": [ { "jobSecret": [] } ], "responses": { "200": { "description": "Arka plan bağlamı olmadan tamamlandı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Arka plan yürütme bağlamında kabul edildi.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "const": true } }, "required": [ "accepted" ], "additionalProperties": false } } } }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/checkout/{token}/status": { "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "description": "Ödeme sayfası URL'sinden rastgele genel tanımlayıcı. Yalnızca bu faturaya okuma erişimi verir." } ], "get": { "tags": [ "Checkout" ], "operationId": "getCheckoutPaymentStatus", "summary": "Aynı ödemeyi oku ve yenile", "description": "Hesap gerekmez. Kimliği doğrulanmış ağ geçidi taşıması üzerinden mevcut bir işlemi sunucu tarafı hız sınırlamasıyla yeniler. Yeni ödeme oluşturulmaz. Hiçbir şey gönderilmediyse null döndürür. Yalnızca fulfillmentReady true olduğunda bir siparişi onaylayın.", "responses": { "200": { "description": "Geçerli temizlenmiş ödeme durumu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "payment": { "oneOf": [ { "$ref": "#/components/schemas/CheckoutPayment" }, { "type": "null" } ] }, "replayed": { "type": "boolean" } }, "required": [ "payment" ], "additionalProperties": false } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "404": { "description": "Kayıt eksik, genel belirteç geçersiz veya istenen kayıt başka bir kullanıcıya ait.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "429": { "description": "Hız sınırı aşıldı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "Sunucu her zaman 60 döndürür; bu, saatlik kotanın dolduğunu garanti etmez." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "502": { "description": "Ağ geçidi yanıtı kullanılamıyor, hatalı veya doğrulanamıyor. Herhangi bir yeniden denemeden önce mevcut ödeme durumunu okuyun.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "GATEWAY_REQUEST_UNCERTAIN", "GATEWAY_INVALID_RESPONSE" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/checkout/{token}/reconcile": { "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "description": "Ödeme sayfası URL'sinden rastgele genel tanımlayıcı. Yalnızca bu faturaya okuma erişimi verir." } ], "post": { "tags": [ "Checkout" ], "operationId": "reconcileCheckoutPayment", "summary": "Yetkili bir durum mutabakatı iste", "description": "Mevcut işlemi okur ve ağ geçidinden sağlayıcı durumunu mutabakat etmesini ister. Ödeme oluşturmaz. Fatura başına dakikada en fazla 3 istek. Fatura artık etkin olmasa bile zaten gönderilmiş ödemeler için kullanılabilir.", "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "APP_ORIGIN ile birebir eşleşmelidir. Sec-Fetch-Site: cross-site reddedilir. Sunucu CORS erişimi sağlamaz.", "schema": { "type": "string", "format": "uri" } } ], "requestBody": { "required": true, "description": "JSON nesnesi. En fazla 16.384 bayt. Bilinmeyen alanlar reddedilir.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyObject" } } } }, "responses": { "200": { "description": "Mutabakat edilmiş ödeme veya null.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "payment": { "oneOf": [ { "$ref": "#/components/schemas/CheckoutPayment" }, { "type": "null" } ] }, "replayed": { "type": "boolean" } }, "required": [ "payment" ], "additionalProperties": false } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "Kayıt eksik, genel belirteç geçersiz veya istenen kayıt başka bir kullanıcıya ait.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "Giriş talebi kullanıldı veya iptal edildi, kimlik doğrulanmadı veya bir destek talebi çakışıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "410": { "description": "Ağ geçidi şifreleme niyeti veya banka meydan okuması süresi doldu. Aynı işlem için yeni bir niyet edinin; değiştirme ödemesi oluşturmayın.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CARD_SESSION_INVALID" ] }, "413": { "description": "Gövde 16.384 baytı aşıyor; /api/support/ask ve Telegram webhook'u için sınır 65.536 bayttır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json gereklidir.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Hız sınırı aşıldı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "Sunucu her zaman 60 döndürür; bu, saatlik kotanın dolduğunu garanti etmez." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "502": { "description": "Ağ geçidi yanıtı kullanılamıyor, hatalı veya doğrulanamıyor. Herhangi bir yeniden denemeden önce mevcut ödeme durumunu okuyun.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "GATEWAY_REQUEST_UNCERTAIN", "GATEWAY_INVALID_RESPONSE" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/checkout/{token}/card-intent": { "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "description": "Ödeme sayfası URL'sinden rastgele genel tanımlayıcı. Yalnızca bu faturaya okuma erişimi verir." } ], "post": { "tags": [ "Checkout" ], "operationId": "createCardEncryptionIntent", "summary": "Ağ geçidi genel anahtarı ve bağlı bir şifreleme niyeti edin", "description": "Özel anahtar yalnızca ağ geçidine aittir. Bir niyet beş dakika içinde sona erer ve satıcı siparişini, para birimini, taban/toplam tutarları, işlem kimlik gücü anahtarını ve amacı bağlar. Ödeme niyetleri etkin bir fatura ve onaylanmış satıcı gerektirir; kod niyetleri mevcut, güncel bir banka sorunu gerektirir. Bu uç nokta PAN, CVV, banka kodu veya özel JWK alanlarını kabul etmez. Fatura başına en fazla 8 niyet ve istemci başına dakikada 12. Şifrelenmiş düz metin, ödeme için {intent,name,country,email?,card:{number,expiration,cvv,holder}} veya kod için {intent,code} biçimindedir. Düz metin yalnızca tarayıcı içinde JWE şifrelemesinden önce birleştirilir.", "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "APP_ORIGIN ile birebir eşleşmelidir. Sec-Fetch-Site: cross-site reddedilir. Sunucu CORS erişimi sağlamaz.", "schema": { "type": "string", "format": "uri" } } ], "requestBody": { "required": true, "description": "JSON nesnesi, en fazla 2048 bayt.", "content": { "application/json": { "schema": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "payment", "code" ], "default": "payment" } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Yalnızca kısa ömürlü niyet ve genel RSA anahtarı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardIntent" } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "Kayıt eksik, genel belirteç geçersiz veya istenen kayıt başka bir kullanıcıya ait.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "Giriş talebi kullanıldı veya iptal edildi, kimlik doğrulanmadı veya bir destek talebi çakışıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "410": { "description": "Ağ geçidi şifreleme niyeti veya banka meydan okuması süresi doldu. Aynı işlem için yeni bir niyet edinin; değiştirme ödemesi oluşturmayın.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CARD_SESSION_INVALID" ] }, "413": { "description": "Gövde 16.384 baytı aşıyor; /api/support/ask ve Telegram webhook'u için sınır 65.536 bayttır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json gereklidir.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Hız sınırı aşıldı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "Sunucu her zaman 60 döndürür; bu, saatlik kotanın dolduğunu garanti etmez." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "502": { "description": "Ağ geçidi yanıtı kullanılamıyor, hatalı veya doğrulanamıyor. Herhangi bir yeniden denemeden önce mevcut ödeme durumunu okuyun.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "GATEWAY_REQUEST_UNCERTAIN", "GATEWAY_INVALID_RESPONSE" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/checkout/{token}/code": { "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "description": "Ödeme sayfası URL'sinden rastgele genel tanımlayıcı. Yalnızca bu faturaya okuma erişimi verir." } ], "post": { "tags": [ "Checkout" ], "operationId": "submitEncryptedBankCode", "summary": "Geçerli banka sorunu için şifrelenmiş bir kodu ilet", "description": "Amaç=code olan bir niyet edinin ve tarayıcıda {intent,code} şifreleyin. Ağ geçidi geçerli sorunu doğrular ve mühürlü niyeti bir kez tüketir. Kevmi düz metin kodu asla almaz. Fatura başına dakikada en fazla 5 gönderim; belirsiz bir yanıttan sonra durumu yenileyin.", "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "APP_ORIGIN ile birebir eşleşmelidir. Sec-Fetch-Site: cross-site reddedilir. Sunucu CORS erişimi sağlamaz.", "schema": { "type": "string", "format": "uri" } } ], "requestBody": { "required": true, "description": "JSON nesnesi. En fazla 16.384 bayt. Bilinmeyen alanlar reddedilir.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sealed": { "$ref": "#/components/schemas/SealedCardData" } }, "required": [ "sealed" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Kod gönderildi; geçerli ödeme durumu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "payment": { "oneOf": [ { "$ref": "#/components/schemas/CheckoutPayment" }, { "type": "null" } ] }, "replayed": { "type": "boolean" } }, "required": [ "payment" ], "additionalProperties": false } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "Kayıt eksik, genel belirteç geçersiz veya istenen kayıt başka bir kullanıcıya ait.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "Giriş talebi kullanıldı veya iptal edildi, kimlik doğrulanmadı veya bir destek talebi çakışıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "410": { "description": "Ağ geçidi şifreleme niyeti veya banka meydan okuması süresi doldu. Aynı işlem için yeni bir niyet edinin; değiştirme ödemesi oluşturmayın.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CARD_SESSION_INVALID" ] }, "413": { "description": "Gövde 16.384 baytı aşıyor; /api/support/ask ve Telegram webhook'u için sınır 65.536 bayttır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json gereklidir.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Hız sınırı aşıldı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "Sunucu her zaman 60 döndürür; bu, saatlik kotanın dolduğunu garanti etmez." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "502": { "description": "Ağ geçidi yanıtı kullanılamıyor, hatalı veya doğrulanamıyor. Herhangi bir yeniden denemeden önce mevcut ödeme durumunu okuyun.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "GATEWAY_REQUEST_UNCERTAIN", "GATEWAY_INVALID_RESPONSE" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/checkout/{token}/crypto-services": { "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "description": "Ödeme sayfası URL'sinden rastgele genel tanımlayıcı. Yalnızca bu faturaya okuma erişimi verir." } ], "get": { "tags": [ "Checkout" ], "operationId": "getCheckoutCryptoServices", "summary": "Geçerli madeni para ve ağ kataloğunu oku", "description": "Yalnızca kripto paralara izin veren bir USDT faturası için. Fatura USDT cinsinden kalır; ağ geçidi seçilen ödeyici madeni parasını fiyatlar. USD'nin USDT'ye eşit olduğunu asla varsaymayın veya transfer tutarını kayan noktalı bir sayıya dönüştürmeyin. Fatura başına dakikada en fazla 10 katalog okuması.", "responses": { "200": { "description": "Ağ geçidi tarafından sağlanan katalog, güncel kullanılabilirlik ve transfer limitleriyle.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "services": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string" }, "network": { "type": "string" }, "networkLabel": { "type": "string" }, "available": { "type": "boolean" }, "minAmount": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "description": "Seçilen transfer madeni parasında tam ondalık değer." }, "maxAmount": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "description": "Seçilen transfer madeni parasında tam ondalık değer." }, "confirmations": { "type": [ "integer", "null" ], "minimum": 0 } }, "required": [ "currency", "network", "networkLabel", "available", "minAmount", "maxAmount", "confirmations" ], "additionalProperties": false } }, "fetchedAt": { "type": "integer", "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." } }, "required": [ "services", "fetchedAt" ], "additionalProperties": false } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "404": { "description": "Kayıt eksik, genel belirteç geçersiz veya istenen kayıt başka bir kullanıcıya ait.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "429": { "description": "Hız sınırı aşıldı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "Sunucu her zaman 60 döndürür; bu, saatlik kotanın dolduğunu garanti etmez." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "502": { "description": "Ağ geçidi yanıtı kullanılamıyor, hatalı veya doğrulanamıyor. Herhangi bir yeniden denemeden önce mevcut ödeme durumunu okuyun.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "GATEWAY_REQUEST_UNCERTAIN", "GATEWAY_INVALID_RESPONSE" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/stores": { "get": { "tags": [ "Account" ], "operationId": "listStores", "summary": "Geçerli hesabın sahip olduğu tüm mağazaları listele", "security": [ { "cookieSession": [] } ], "responses": { "200": { "description": "Mağaza kimlikleri hesap kimliklerinden farklıdır. Hiçbir sır ifşa edilmez.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "stores": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/Store" } }, "defaultStoreId": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" } }, "required": [ "stores", "defaultStoreId" ], "additionalProperties": false } } } }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } }, "post": { "tags": [ "Account" ], "operationId": "createStore", "summary": "Ayrı bir mağaza oluştur", "description": "Hesap başına en fazla 100 mağaza ve hesap başına saatte 10 oluşturma. Yeni bir mağaza, ödeme başlatmadan önce kendi web sitesi onayına ihtiyaç duyar.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "APP_ORIGIN ile birebir eşleşmelidir. Sec-Fetch-Site: cross-site reddedilir. Sunucu CORS erişimi sağlamaz.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "GET /api/auth/me veya başarılı giriş tamamlamadan gelen geçerli oturum belirteci.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "requestBody": { "required": true, "description": "JSON nesnesi. En fazla 16.384 bayt. Bilinmeyen alanlar reddedilir.", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Oluşturuldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "store": { "$ref": "#/components/schemas/Store" } }, "required": [ "store" ], "additionalProperties": false } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "409": { "description": "Giriş talebi kullanıldı veya iptal edildi, kimlik doğrulanmadı veya bir destek talebi çakışıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "429": { "description": "Hız sınırı aşıldı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "Sunucu her zaman 60 döndürür; bu, saatlik kotanın dolduğunu garanti etmez." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/stores/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" } } ], "patch": { "tags": [ "Account" ], "operationId": "updateStore", "summary": "Sahip olunan bir mağazayı yeniden adlandırın veya varsayılan KDV'sini değiştirin", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "APP_ORIGIN ile birebir eşleşmelidir. Sec-Fetch-Site: cross-site reddedilir. Sunucu CORS erişimi sağlamaz.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "GET /api/auth/me veya başarılı giriş tamamlamadan gelen geçerli oturum belirteci.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "requestBody": { "required": true, "description": "JSON nesnesi. En fazla 16.384 bayt. Bilinmeyen alanlar reddedilir.", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "vatPayer": { "type": "string", "enum": [ "customer", "merchant" ] } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Mevcut fatura kotasyonları değişmez.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "store": { "$ref": "#/components/schemas/Store" } }, "required": [ "store" ], "additionalProperties": false } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "Kayıt eksik, genel belirteç geçersiz veya istenen kayıt başka bir kullanıcıya ait.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/exchange-rates": { "get": { "tags": [ "Payments" ], "operationId": "getReferenceExchangeRate", "summary": "Geçerli USD/RUB referans kurunu al", "description": "Sunucuda bir saat önbelleğe alınır. Sayısal kur, USD başına RUB'un milyonda biri olarak kullanılır. Yedek kotasyon uydurulmaz. Fatura oluşturmada kullanılır; mevcut bir fatura kendi kurunu korur.", "security": [], "responses": { "200": { "description": "Resmi kaynak, yayın tarihi ve alma zamanı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "rate": { "$ref": "#/components/schemas/ExchangeRate" } }, "required": [ "rate" ], "additionalProperties": false } } } }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/account/dashboard": { "get": { "tags": [ "Account" ], "operationId": "getAccountDashboard", "summary": "Bir mağaza veya sahip olunan tüm mağazalar için doğrulanmış tahsilatları oku", "description": "Net tahsilatlar çekilebilir bir bakiye değildir. Eski para birimleri ayrı kalır. Toplamlar tüm zamanları kapsar; günlük/yöntem dökümleri istenen UTC dönemini kullanır.", "security": [ { "cookieSession": [] } ], "parameters": [ { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Tarayıcı oturumu için sahip olunan bir mağaza seçin. İlk mağazayı kullanmak için atlayın. API anahtarları bu başlığı yok sayar ve her zaman değişmez mağaza bağlamasını kullanır. all değeri salt okunurdur ve yalnızca gösterge paneli ve fatura listesi uç noktaları tarafından desteklenir." }, { "name": "days", "in": "query", "schema": { "type": "integer", "enum": [ 7, 30 ], "default": 7 } } ], "responses": { "200": { "description": "Salt okunur muhasebe özeti.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "storeId": { "type": [ "string", "null" ] }, "stores": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "name": { "type": "string" }, "currency": { "type": [ "string", "null" ] }, "invoices": { "type": "integer" }, "netMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." } }, "required": [ "id", "name", "currency", "invoices", "netMinor" ], "additionalProperties": false } }, "totals": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string" }, "invoices": { "type": "integer" }, "succeeded": { "type": "integer" }, "grossMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "netMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." } }, "required": [ "currency", "invoices", "succeeded", "grossMinor", "netMinor" ], "additionalProperties": false } }, "daily": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string" }, "day": { "type": "string" }, "count": { "type": "integer" }, "grossMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." } }, "required": [ "currency", "day", "count", "grossMinor" ], "additionalProperties": false } }, "methods": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string" }, "method": { "type": "string" }, "count": { "type": "integer" }, "grossMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." } }, "required": [ "currency", "method", "count", "grossMinor" ], "additionalProperties": false } }, "days": { "type": "integer", "enum": [ 7, 30 ] }, "from": { "type": "integer", "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." }, "generatedAt": { "type": "integer", "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." }, "accountingBasis": { "type": "string", "const": "verified_receipts" }, "withdrawableBalance": { "type": "null" }, "payoutCreationAvailable": { "type": "boolean", "const": false }, "payoutRequestAvailable": { "type": "boolean", "const": true } }, "required": [ "storeId", "stores", "totals", "daily", "methods", "days", "from", "generatedAt", "accountingBasis", "withdrawableBalance", "payoutCreationAvailable", "payoutRequestAvailable" ], "additionalProperties": false } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "404": { "description": "Kayıt eksik, genel belirteç geçersiz veya istenen kayıt başka bir kullanıcıya ait.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "503": { "description": "Bir entegrasyon veya depolama kullanılamıyor, bir olay işleniyor veya hizmet kullanılamıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/account/payout-requests": { "get": { "tags": [ "Account" ], "operationId": "accountListPayoutRequests", "summary": "Sahip olunan ödeme inceleme taleplerini listele", "description": "Oturum ve sahip olunan X-Kevmi-Store kapsamı; salt okunur toplama için tümüne izin verilir. Son 100 talep ve sunucu mutabakat takvimini döndürür. Uluslararası kartlar ve Alipay: yalnızca 1. ve 15. gün, Asia/Qyzylorda UTC+5. Talepler herhangi bir gün gönderilebilir. Fon rezervasyonu veya otomatik transfer yoktur.", "security": [ { "cookieSession": [] } ], "responses": { "200": { "description": "Talepler, takvim, storeId ve executionMode=manual_review.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "requests": { "type": "array", "maxItems": 100, "items": { "type": "object", "properties": { "id": { "type": "string" }, "storeId": { "type": "string" }, "storeName": { "type": "string" }, "ticketId": { "type": "string" }, "source": { "type": "string", "enum": [ "card", "alipay", "sbp", "crypto" ] }, "amountMinor": { "type": "integer", "minimum": 1 }, "address": { "type": "string" }, "status": { "type": "string", "enum": [ "requested", "approved", "rejected", "cancelled" ] }, "scheduledDate": { "type": [ "string", "null" ] }, "adminReason": { "type": [ "string", "null" ] }, "reviewedAt": { "type": [ "integer", "null" ] }, "createdAt": { "type": "integer", "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." } }, "required": [ "id", "storeId", "storeName", "ticketId", "source", "amountMinor", "address", "status", "scheduledDate", "adminReason", "reviewedAt", "createdAt" ], "additionalProperties": false } }, "storeId": { "type": [ "string", "null" ] }, "calendar": { "type": "object", "properties": { "timeZone": { "type": "string", "const": "Asia/Qyzylorda" }, "utcOffset": { "type": "string", "const": "+05:00" }, "requestAnyDay": { "type": "boolean", "const": true }, "scheduled": { "type": "boolean" }, "days": { "type": "array", "items": { "type": "integer", "enum": [ 1, 15 ] } }, "today": { "type": "string", "format": "date" }, "executionAllowed": { "type": "boolean" }, "nextDate": { "type": [ "string", "null" ] } }, "required": [ "timeZone", "utcOffset", "requestAnyDay", "scheduled", "days", "today", "executionAllowed", "nextDate" ], "additionalProperties": false }, "calendars": { "type": "object", "properties": { "card": { "type": "object", "properties": { "timeZone": { "type": "string", "const": "Asia/Qyzylorda" }, "utcOffset": { "type": "string", "const": "+05:00" }, "requestAnyDay": { "type": "boolean", "const": true }, "scheduled": { "type": "boolean" }, "days": { "type": "array", "items": { "type": "integer", "enum": [ 1, 15 ] } }, "today": { "type": "string", "format": "date" }, "executionAllowed": { "type": "boolean" }, "nextDate": { "type": [ "string", "null" ] } }, "required": [ "timeZone", "utcOffset", "requestAnyDay", "scheduled", "days", "today", "executionAllowed", "nextDate" ], "additionalProperties": false }, "alipay": { "type": "object", "properties": { "timeZone": { "type": "string", "const": "Asia/Qyzylorda" }, "utcOffset": { "type": "string", "const": "+05:00" }, "requestAnyDay": { "type": "boolean", "const": true }, "scheduled": { "type": "boolean" }, "days": { "type": "array", "items": { "type": "integer", "enum": [ 1, 15 ] } }, "today": { "type": "string", "format": "date" }, "executionAllowed": { "type": "boolean" }, "nextDate": { "type": [ "string", "null" ] } }, "required": [ "timeZone", "utcOffset", "requestAnyDay", "scheduled", "days", "today", "executionAllowed", "nextDate" ], "additionalProperties": false }, "sbp": { "type": "object", "properties": { "timeZone": { "type": "string", "const": "Asia/Qyzylorda" }, "utcOffset": { "type": "string", "const": "+05:00" }, "requestAnyDay": { "type": "boolean", "const": true }, "scheduled": { "type": "boolean" }, "days": { "type": "array", "items": { "type": "integer", "enum": [ 1, 15 ] } }, "today": { "type": "string", "format": "date" }, "executionAllowed": { "type": "boolean" }, "nextDate": { "type": [ "string", "null" ] } }, "required": [ "timeZone", "utcOffset", "requestAnyDay", "scheduled", "days", "today", "executionAllowed", "nextDate" ], "additionalProperties": false }, "crypto": { "type": "object", "properties": { "timeZone": { "type": "string", "const": "Asia/Qyzylorda" }, "utcOffset": { "type": "string", "const": "+05:00" }, "requestAnyDay": { "type": "boolean", "const": true }, "scheduled": { "type": "boolean" }, "days": { "type": "array", "items": { "type": "integer", "enum": [ 1, 15 ] } }, "today": { "type": "string", "format": "date" }, "executionAllowed": { "type": "boolean" }, "nextDate": { "type": [ "string", "null" ] } }, "required": [ "timeZone", "utcOffset", "requestAnyDay", "scheduled", "days", "today", "executionAllowed", "nextDate" ], "additionalProperties": false } }, "required": [ "card", "alipay", "sbp", "crypto" ], "additionalProperties": false }, "currency": { "type": "string", "const": "USD" }, "asset": { "type": "string", "const": "USDT" }, "network": { "type": "string", "const": "TRC20" }, "executionMode": { "type": "string", "const": "manual_review" }, "withdrawableBalance": { "type": "null" } }, "required": [ "requests", "storeId", "calendar", "calendars", "currency", "asset", "network", "executionMode", "withdrawableBalance" ], "additionalProperties": false } } } }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] } } }, "post": { "tags": [ "Account" ], "operationId": "createPayoutReviewRequest", "summary": "Manuel inceleme için bir mağaza ödeme talebi gönder", "description": "Bireysel sahip olunan bir mağaza, oturum, CSRF ve Origin gerektirir. requestId bir idempotency UUID'sidir; çakışan yeniden kullanım reddedilir. Bağlantılı bir destek bileti ve kalıcı moderatör uyarısı oluşturur. Talep edilen USD tutarı, ücretler, mevcut fonlar, dönüşüm ve hedef manuel doğrulama gerektirir. Fon ayırmaz veya bir transfer gerçekleştirmez.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "APP_ORIGIN ile birebir eşleşmelidir. Sec-Fetch-Site: cross-site reddedilir. Sunucu CORS erişimi sağlamaz.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "GET /api/auth/me veya başarılı giriş tamamlamadan gelen geçerli oturum belirteci.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "requestBody": { "required": true, "description": "JSON nesnesi. En fazla 16.384 bayt. Bilinmeyen alanlar reddedilir.", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid" }, "source": { "type": "string", "enum": [ "card", "alipay", "sbp", "crypto" ] }, "amountMinor": { "type": "integer", "minimum": 1, "maximum": 100000000, "description": "Talep edilen kaynak tutarı USD alt birimleri cinsinden. Çekilebilir bir bakiye veya dönüşüm teklifi değildir." }, "address": { "type": "string", "pattern": "^T[1-9A-HJ-NP-Za-km-z]{33}$", "description": "USDT TRC20 hedefi. Biçim doğrulaması sahipliği tespit etmez." } }, "required": [ "requestId", "source", "amountMinor", "address" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Idempotent mevcut talep.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "ticketId": { "type": "string" }, "status": { "type": "string" }, "scheduledDate": { "type": [ "string", "null" ] }, "calendar": { "type": "object", "properties": { "timeZone": { "type": "string", "const": "Asia/Qyzylorda" }, "utcOffset": { "type": "string", "const": "+05:00" }, "requestAnyDay": { "type": "boolean", "const": true }, "scheduled": { "type": "boolean" }, "days": { "type": "array", "items": { "type": "integer", "enum": [ 1, 15 ] } }, "today": { "type": "string", "format": "date" }, "executionAllowed": { "type": "boolean" }, "nextDate": { "type": [ "string", "null" ] } }, "required": [ "timeZone", "utcOffset", "requestAnyDay", "scheduled", "days", "today", "executionAllowed", "nextDate" ], "additionalProperties": false } }, "required": [ "id", "ticketId", "status" ], "additionalProperties": false } } } }, "201": { "description": "Talep kaydedildi.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "ticketId": { "type": "string" }, "status": { "type": "string" }, "scheduledDate": { "type": [ "string", "null" ] }, "calendar": { "type": "object", "properties": { "timeZone": { "type": "string", "const": "Asia/Qyzylorda" }, "utcOffset": { "type": "string", "const": "+05:00" }, "requestAnyDay": { "type": "boolean", "const": true }, "scheduled": { "type": "boolean" }, "days": { "type": "array", "items": { "type": "integer", "enum": [ 1, 15 ] } }, "today": { "type": "string", "format": "date" }, "executionAllowed": { "type": "boolean" }, "nextDate": { "type": [ "string", "null" ] } }, "required": [ "timeZone", "utcOffset", "requestAnyDay", "scheduled", "days", "today", "executionAllowed", "nextDate" ], "additionalProperties": false } }, "required": [ "id", "ticketId", "status" ], "additionalProperties": false } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "409": { "description": "Giriş talebi kullanıldı veya iptal edildi, kimlik doğrulanmadı veya bir destek talebi çakışıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "429": { "description": "Hız sınırı aşıldı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "Sunucu her zaman 60 döndürür; bu, saatlik kotanın dolduğunu garanti etmez." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] } } } }, "/api/account/payout-requests/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^pyr_[a-f0-9-]{36}$" } } ], "post": { "tags": [ "Account" ], "operationId": "accountReviewPayoutRequest", "summary": "Sahip olunan bekleyen bir ödeme talebini iptal et", "description": "Talebin sahibi olan bireysel mağazayı gerektirir. Yalnızca talep edilen durum; sonraki geçişler reddedilir. Uluslararası kart veya Alipay taleplerinin onayı, sunucu saatine göre yalnızca 1./15. gün UTC+5'te izin verilir. Onay, tamamlanmış bir transfer değildir. transferExecuted=false döndürür. Moderatör geçişleri atomik olarak denetlenir.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "APP_ORIGIN ile birebir eşleşmelidir. Sec-Fetch-Site: cross-site reddedilir. Sunucu CORS erişimi sağlamaz.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "GET /api/auth/me veya başarılı giriş tamamlamadan gelen geçerli oturum belirteci.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "requestBody": { "required": true, "description": "JSON nesnesi. En fazla 16.384 bayt. Bilinmeyen alanlar reddedilir.", "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "cancel" ] } }, "required": [ "action" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Güncellenen talep. Hiçbir transfer gerçekleştirilmedi.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "approved", "rejected", "cancelled" ] }, "executionMode": { "type": "string", "const": "manual_review" }, "transferExecuted": { "type": "boolean", "const": false } }, "required": [ "id", "status", "executionMode", "transferExecuted" ], "additionalProperties": false } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "Kayıt eksik, genel belirteç geçersiz veya istenen kayıt başka bir kullanıcıya ait.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "Giriş talebi kullanıldı veya iptal edildi, kimlik doğrulanmadı veya bir destek talebi çakışıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] } } } }, "/api/admin/payout-requests": { "get": { "tags": [ "Account" ], "operationId": "adminListPayoutRequests", "summary": "Moderatör olarak ödeme inceleme taleplerini listele", "description": "Sunucu tarafı Telegram kimliği izin listesinden oturum açmış bir moderatör gerektirir. Tanımlayıcılar asla yetki vermez. Sırlar, kimlik bilgisi karmaları ve kart ayrıntıları hariç tutulur. Son 100 talep ve sunucu mutabakat takvimini döndürür. Uluslararası kartlar ve Alipay: yalnızca 1. ve 15. gün, Asia/Qyzylorda UTC+5. Talepler herhangi bir gün gönderilebilir. Fon rezervasyonu veya otomatik transfer yoktur.", "security": [ { "cookieSession": [] } ], "responses": { "200": { "description": "Talepler, takvim, storeId ve executionMode=manual_review.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "requests": { "type": "array", "maxItems": 100, "items": { "type": "object", "properties": { "id": { "type": "string" }, "storeId": { "type": "string" }, "storeName": { "type": "string" }, "ticketId": { "type": "string" }, "source": { "type": "string", "enum": [ "card", "alipay", "sbp", "crypto" ] }, "amountMinor": { "type": "integer", "minimum": 1 }, "address": { "type": "string" }, "status": { "type": "string", "enum": [ "requested", "approved", "rejected", "cancelled" ] }, "scheduledDate": { "type": [ "string", "null" ] }, "adminReason": { "type": [ "string", "null" ] }, "reviewedAt": { "type": [ "integer", "null" ] }, "createdAt": { "type": "integer", "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." } }, "required": [ "id", "storeId", "storeName", "ticketId", "source", "amountMinor", "address", "status", "scheduledDate", "adminReason", "reviewedAt", "createdAt" ], "additionalProperties": false } }, "storeId": { "type": [ "string", "null" ] }, "calendar": { "type": "object", "properties": { "timeZone": { "type": "string", "const": "Asia/Qyzylorda" }, "utcOffset": { "type": "string", "const": "+05:00" }, "requestAnyDay": { "type": "boolean", "const": true }, "scheduled": { "type": "boolean" }, "days": { "type": "array", "items": { "type": "integer", "enum": [ 1, 15 ] } }, "today": { "type": "string", "format": "date" }, "executionAllowed": { "type": "boolean" }, "nextDate": { "type": [ "string", "null" ] } }, "required": [ "timeZone", "utcOffset", "requestAnyDay", "scheduled", "days", "today", "executionAllowed", "nextDate" ], "additionalProperties": false }, "calendars": { "type": "object", "properties": { "card": { "type": "object", "properties": { "timeZone": { "type": "string", "const": "Asia/Qyzylorda" }, "utcOffset": { "type": "string", "const": "+05:00" }, "requestAnyDay": { "type": "boolean", "const": true }, "scheduled": { "type": "boolean" }, "days": { "type": "array", "items": { "type": "integer", "enum": [ 1, 15 ] } }, "today": { "type": "string", "format": "date" }, "executionAllowed": { "type": "boolean" }, "nextDate": { "type": [ "string", "null" ] } }, "required": [ "timeZone", "utcOffset", "requestAnyDay", "scheduled", "days", "today", "executionAllowed", "nextDate" ], "additionalProperties": false }, "alipay": { "type": "object", "properties": { "timeZone": { "type": "string", "const": "Asia/Qyzylorda" }, "utcOffset": { "type": "string", "const": "+05:00" }, "requestAnyDay": { "type": "boolean", "const": true }, "scheduled": { "type": "boolean" }, "days": { "type": "array", "items": { "type": "integer", "enum": [ 1, 15 ] } }, "today": { "type": "string", "format": "date" }, "executionAllowed": { "type": "boolean" }, "nextDate": { "type": [ "string", "null" ] } }, "required": [ "timeZone", "utcOffset", "requestAnyDay", "scheduled", "days", "today", "executionAllowed", "nextDate" ], "additionalProperties": false }, "sbp": { "type": "object", "properties": { "timeZone": { "type": "string", "const": "Asia/Qyzylorda" }, "utcOffset": { "type": "string", "const": "+05:00" }, "requestAnyDay": { "type": "boolean", "const": true }, "scheduled": { "type": "boolean" }, "days": { "type": "array", "items": { "type": "integer", "enum": [ 1, 15 ] } }, "today": { "type": "string", "format": "date" }, "executionAllowed": { "type": "boolean" }, "nextDate": { "type": [ "string", "null" ] } }, "required": [ "timeZone", "utcOffset", "requestAnyDay", "scheduled", "days", "today", "executionAllowed", "nextDate" ], "additionalProperties": false }, "crypto": { "type": "object", "properties": { "timeZone": { "type": "string", "const": "Asia/Qyzylorda" }, "utcOffset": { "type": "string", "const": "+05:00" }, "requestAnyDay": { "type": "boolean", "const": true }, "scheduled": { "type": "boolean" }, "days": { "type": "array", "items": { "type": "integer", "enum": [ 1, 15 ] } }, "today": { "type": "string", "format": "date" }, "executionAllowed": { "type": "boolean" }, "nextDate": { "type": [ "string", "null" ] } }, "required": [ "timeZone", "utcOffset", "requestAnyDay", "scheduled", "days", "today", "executionAllowed", "nextDate" ], "additionalProperties": false } }, "required": [ "card", "alipay", "sbp", "crypto" ], "additionalProperties": false }, "currency": { "type": "string", "const": "USD" }, "asset": { "type": "string", "const": "USDT" }, "network": { "type": "string", "const": "TRC20" }, "executionMode": { "type": "string", "const": "manual_review" }, "withdrawableBalance": { "type": "null" } }, "required": [ "requests", "storeId", "calendar", "calendars", "currency", "asset", "network", "executionMode", "withdrawableBalance" ], "additionalProperties": false } } } }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] } } } }, "/api/admin/payout-requests/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^pyr_[a-f0-9-]{36}$" } } ], "post": { "tags": [ "Account" ], "operationId": "adminReviewPayoutRequest", "summary": "Bir ödeme inceleme talebini onayla veya reddet", "description": "Sunucu tarafı Telegram kimliği izin listesinden oturum açmış bir moderatör gerektirir. Tanımlayıcılar asla yetki vermez. Sırlar, kimlik bilgisi karmaları ve kart ayrıntıları hariç tutulur. Yalnızca talep edilen durum; sonraki geçişler reddedilir. Uluslararası kart veya Alipay taleplerinin onayı, sunucu saatine göre yalnızca 1./15. gün UTC+5'te izin verilir. Onay, tamamlanmış bir transfer değildir. transferExecuted=false döndürür. Moderatör geçişleri atomik olarak denetlenir.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "APP_ORIGIN ile birebir eşleşmelidir. Sec-Fetch-Site: cross-site reddedilir. Sunucu CORS erişimi sağlamaz.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "GET /api/auth/me veya başarılı giriş tamamlamadan gelen geçerli oturum belirteci.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "requestBody": { "required": true, "description": "JSON nesnesi. En fazla 16.384 bayt. Bilinmeyen alanlar reddedilir.", "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "approve", "reject" ] }, "reason": { "type": "string", "minLength": 5, "maxLength": 500 } }, "required": [ "action", "reason" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Güncellenen talep. Hiçbir transfer gerçekleştirilmedi.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "approved", "rejected", "cancelled" ] }, "executionMode": { "type": "string", "const": "manual_review" }, "transferExecuted": { "type": "boolean", "const": false } }, "required": [ "id", "status", "executionMode", "transferExecuted" ], "additionalProperties": false } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "Kayıt eksik, genel belirteç geçersiz veya istenen kayıt başka bir kullanıcıya ait.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "Giriş talebi kullanıldı veya iptal edildi, kimlik doğrulanmadı veya bir destek talebi çakışıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] } } } }, "/api/admin/tickets": { "get": { "tags": [ "Support" ], "operationId": "adminListTickets", "summary": "Moderatörler için en son destek isteklerini listele", "description": "Sunucu tarafı Telegram kimliği izin listesinden oturum açmış bir moderatör gerektirir. Tanımlayıcılar asla yetki vermez. Sırlar, kimlik bilgisi karmaları ve kart ayrıntıları hariç tutulur.", "security": [ { "cookieSession": [] } ], "responses": { "200": { "description": "En son 100 istek.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] } } } }, "/api/admin/tickets/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^tkt_[a-f0-9-]{36}$" } } ], "get": { "tags": [ "Support" ], "operationId": "adminReadTicket", "summary": "Bir destek isteğini ve uzman yanıtlarını oku", "description": "Sunucu tarafı Telegram kimliği izin listesinden oturum açmış bir moderatör gerektirir. Tanımlayıcılar asla yetki vermez. Sırlar, kimlik bilgisi karmaları ve kart ayrıntıları hariç tutulur.", "security": [ { "cookieSession": [] } ], "responses": { "200": { "description": "İstek ve kaydedilmiş yanıtlar.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "Kayıt eksik, genel belirteç geçersiz veya istenen kayıt başka bir kullanıcıya ait.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] } } }, "post": { "tags": [ "Support" ], "operationId": "adminReplyTicket", "summary": "Bir uzman yanıtını kaydet ve sahibini bilgilendir", "description": "Sunucu tarafı Telegram kimliği izin listesinden oturum açmış bir moderatör gerektirir. Tanımlayıcılar asla yetki vermez. Sırlar, kimlik bilgisi karmaları ve kart ayrıntıları hariç tutulur. requestId idempotans sağlar; başka bir mesaj için yeniden kullanmak reddedilir.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "APP_ORIGIN ile birebir eşleşmelidir. Sec-Fetch-Site: cross-site reddedilir. Sunucu CORS erişimi sağlamaz.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "GET /api/auth/me veya başarılı giriş tamamlamadan gelen geçerli oturum belirteci.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "requestBody": { "required": true, "description": "JSON nesnesi. En fazla 16.384 bayt. Bilinmeyen alanlar reddedilir.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "minLength": 2, "maxLength": 4000 }, "requestId": { "type": "string", "format": "uuid" } }, "required": [ "message", "requestId" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Kaydedilmiş yanıt.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "$ref": "#/components/schemas/SupportReply" } }, "required": [ "reply" ], "additionalProperties": false } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "Kayıt eksik, genel belirteç geçersiz veya istenen kayıt başka bir kullanıcıya ait.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "Giriş talebi kullanıldı veya iptal edildi, kimlik doğrulanmadı veya bir destek talebi çakışıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "429": { "description": "Hız sınırı aşıldı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "Sunucu her zaman 60 döndürür; bu, saatlik kotanın dolduğunu garanti etmez." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] } } } }, "/api/admin/project": { "get": { "tags": [ "Account" ], "operationId": "adminProjectOverview", "summary": "Proje sayılarını, doğrulanmış makbuzları, yapılandırma hazır olma durumunu ve kontrolleri oku", "description": "Sunucu tarafı Telegram kimliği izin listesinden oturum açmış bir moderatör gerektirir. Tanımlayıcılar asla yetki vermez. Sırlar, kimlik bilgisi karmaları ve kart ayrıntıları hariç tutulur. Yapılandırma hazır olma durumu canlı bir sağlayıcı sağlık kontrolü değildir. Makbuzlar çekilebilir bir bakiye değildir.", "security": [ { "cookieSession": [] } ], "responses": { "200": { "description": "Proje genel bakışı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] } } } }, "/api/admin/project/{section}": { "parameters": [ { "name": "section", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "users", "stores", "payments", "keys", "webhooks", "events", "audit" ] } } ], "get": { "tags": [ "Account" ], "operationId": "adminListProjectRecords", "summary": "Proje kayıtlarını ara ve sayfalandır", "description": "Sunucu tarafı Telegram kimliği izin listesinden oturum açmış bir moderatör gerektirir. Tanımlayıcılar asla yetki vermez. Sırlar, kimlik bilgisi karmaları ve kart ayrıntıları hariç tutulur.", "security": [ { "cookieSession": [] } ], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 120 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000 } } ], "responses": { "200": { "description": "En fazla 50 kayıt ve nextPage.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] } } } }, "/api/admin/project/action": { "post": { "tags": [ "Account" ], "operationId": "adminProjectAction", "summary": "Kontrollü, denetlenmiş bir proje eylemi gerçekleştirin", "description": "Sunucu tarafındaki Telegram ID izin listesinden oturum açmış bir moderatör gerektirir. Tanımlayıcılar asla yetki vermez. Sırlar, kimlik bilgisi özetleri ve kart ayrıntıları hariç tutulur. Bir neden gerektirir. Yöneticiler panel kısıtlamalarından korunur. Ödeme başarısı, iadeler, ödemeler ve isteğe bağlı sunucu komutları bu uç nokta aracılığıyla uydurulamaz.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "APP_ORIGIN ile birebir eşleşmelidir. Sec-Fetch-Site: cross-site reddedilir. Sunucu CORS erişimi sağlamaz.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "GET /api/auth/me veya başarılı giriş tamamlamadan gelen geçerli oturum belirteci.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "requestBody": { "required": true, "description": "JSON nesnesi. En fazla 16.384 bayt. Bilinmeyen alanlar reddedilir.", "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "block-user", "unblock-user", "revoke-sessions", "block-store", "unblock-store", "pause-payment", "cancel-payment", "revoke-key", "disable-webhook", "set-methods", "set-ai" ] }, "targetId": { "type": "string", "maxLength": 100 }, "reason": { "type": "string", "minLength": 5, "maxLength": 500 }, "methods": { "type": "array", "uniqueItems": true, "items": { "type": "string", "enum": [ "card", "alipay", "sbp", "crypto" ] } }, "enabled": { "type": "boolean" } }, "required": [ "action", "reason" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Eylem ve denetim kaydı atomik olarak kaydedilir.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Geçersiz JSON, bilinmeyen alan veya geçersiz değer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Geçerli oturum yok; webhook için geçersiz bir sır.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Origin, CSRF veya tarayıcı bağlama doğrulaması başarısız oldu.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "Kayıt eksik, genel belirteç geçersiz veya istenen kayıt başka bir kullanıcıya ait.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "Giriş talebi kullanıldı veya iptal edildi, kimlik doğrulanmadı veya bir destek talebi çakışıyor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "429": { "description": "Hız sınırı aşıldı.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "Sunucu her zaman 60 döndürür; bu, saatlik kotanın dolduğunu garanti etmez." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] } } } } }, "components": { "securitySchemes": { "cookieSession": { "type": "apiKey", "in": "cookie", "name": "__Host-kevmi-session", "description": "Rastgele oturum belirteci, Secure/HttpOnly/SameSite=Lax, 24 saat geçerli. Veritabanında bir karması saklanır. Yalnızca doğrulanmış Telegram oturum açma işleminden sonra verilir." }, "browserProof": { "type": "apiKey", "in": "cookie", "name": "__Host-kevmi-login", "description": "Baştan itibaren HttpOnly çerezi: challengeId.proof, 300 saniye geçerli. Telegram derin bağlantısından hariç tutulur." }, "csrfToken": { "type": "apiKey", "in": "header", "name": "X-CSRF-Token", "description": "/api/auth/me veya /api/auth/telegram/complete tarafından verilen oturum CSRF belirteci. Mutasyonlar ayrıca tam Origin gerektirir." }, "telegramWebhookSecret": { "type": "apiKey", "in": "header", "name": "X-Telegram-Bot-Api-Secret-Token", "description": "Ayrı sunucu tarafından yapılandırılmış webhook sırrı. Değeri özeldir. Bu bot belirteci değildir." }, "merchantKey": { "type": "http", "scheme": "bearer", "bearerFormat": "kv_live_…", "description": "Kapsamlı satıcı API anahtarı. Yalnızca karması saklanır. Yalnızca sunucudan sunucuya kullanım içindir; asla bir pencere öğesine veya tarayıcı paketine koymayın." }, "gatewaySignature": { "type": "apiKey", "in": "header", "name": "Kevmi-Signature", "description": "t=,v1=. Maksimum zaman farkı: 300 saniye." }, "jobSecret": { "type": "http", "scheme": "bearer", "description": "Ayrı yalnızca sunucu JOBS_SECRET. Bir satıcı API anahtarı değildir." }, "nativeGatewaySignature": { "type": "apiKey", "in": "header", "name": "X-Gateway-Signature", "description": "v1=; satıcı Kevmi-Signature'dan ayrıdır." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "EmptyObject": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "Config": { "type": "object", "properties": { "telegram": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "botUsername": { "type": [ "string", "null" ] } }, "required": [ "enabled", "botUsername" ], "additionalProperties": false }, "support": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "search", "ai" ] }, "available": { "type": "boolean", "const": true } }, "required": [ "mode", "available" ], "additionalProperties": false }, "gateway": { "type": "object", "properties": { "configured": { "type": "boolean" }, "connected": { "type": "boolean", "const": false, "description": "Genel yapılandırma uç noktası ağ geçidi sağlığını yoklamaz. Yapılandırma, başarılı bir canlı bağlantı kontrolü değildir." }, "status": { "type": "string", "enum": [ "configured", "not_configured" ] } }, "required": [ "configured", "connected", "status" ], "additionalProperties": false }, "capabilities": { "type": "object", "properties": { "server": { "type": "boolean", "const": true }, "account": { "type": "boolean" }, "notifications": { "type": "boolean" }, "tickets": { "type": "boolean" }, "directPaymentsOnly": { "type": "boolean", "const": true }, "paymentLinks": { "type": "boolean", "description": "D1, sunucu faturaları için yapılandırılmıştır. Bu ödeme hazırlığını göstermez." }, "apiKeys": { "type": "boolean" }, "webhooks": { "type": "boolean" }, "widgets": { "type": "boolean" }, "applications": { "type": "boolean" }, "applicationNotifications": { "type": "boolean" } }, "required": [ "server", "account", "notifications", "tickets", "directPaymentsOnly", "paymentLinks", "apiKeys", "webhooks", "widgets", "applications", "applicationNotifications" ], "additionalProperties": false } }, "required": [ "telegram", "support", "gateway", "capabilities" ], "additionalProperties": false }, "Health": { "type": "object", "properties": { "telegram": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "botUsername": { "type": [ "string", "null" ] } }, "required": [ "enabled", "botUsername" ], "additionalProperties": false }, "support": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "search", "ai" ] }, "available": { "type": "boolean", "const": true } }, "required": [ "mode", "available" ], "additionalProperties": false }, "gateway": { "type": "object", "properties": { "configured": { "type": "boolean" }, "connected": { "type": "boolean", "const": false, "description": "Genel yapılandırma uç noktası ağ geçidi sağlığını yoklamaz. Yapılandırma, başarılı bir canlı bağlantı kontrolü değildir." }, "status": { "type": "string", "enum": [ "configured", "not_configured" ] } }, "required": [ "configured", "connected", "status" ], "additionalProperties": false }, "capabilities": { "type": "object", "properties": { "server": { "type": "boolean", "const": true }, "account": { "type": "boolean" }, "notifications": { "type": "boolean" }, "tickets": { "type": "boolean" }, "directPaymentsOnly": { "type": "boolean", "const": true }, "paymentLinks": { "type": "boolean", "description": "D1, sunucu faturaları için yapılandırılmıştır. Bu ödeme hazırlığını göstermez." }, "apiKeys": { "type": "boolean" }, "webhooks": { "type": "boolean" }, "widgets": { "type": "boolean" }, "applications": { "type": "boolean" }, "applicationNotifications": { "type": "boolean" } }, "required": [ "server", "account", "notifications", "tickets", "directPaymentsOnly", "paymentLinks", "apiKeys", "webhooks", "widgets", "applications", "applicationNotifications" ], "additionalProperties": false }, "status": { "type": "string", "enum": [ "ok", "degraded" ] }, "storage": { "type": "string", "enum": [ "ready", "not_configured", "unavailable" ] } }, "required": [ "telegram", "support", "gateway", "capabilities", "status", "storage" ], "additionalProperties": false }, "NotificationPreferences": { "type": "object", "properties": { "payments": { "type": "boolean" }, "payouts": { "type": "boolean" }, "support": { "type": "boolean" }, "security": { "type": "boolean" } }, "required": [ "payments", "payouts", "support", "security" ], "additionalProperties": false }, "SettingsPatch": { "type": "object", "properties": { "storeName": { "type": "string", "minLength": 1, "x-trimmedMaxLength": 80, "x-trimmedMinLength": 1, "description": "Çevreleyen boşluklar kırpılır. Kırpma sonrası uzunluk: 1–80 karakter. Sekmeler ve satır sonları dışındaki kontrol karakterleri yasaktır." }, "vatPayer": { "type": "string", "enum": [ "customer", "merchant" ] }, "notifications": { "type": "object", "properties": { "payments": { "type": "boolean" }, "payouts": { "type": "boolean" }, "support": { "type": "boolean" }, "security": { "type": "boolean" } }, "required": [], "additionalProperties": false } }, "required": [], "additionalProperties": false }, "User": { "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "type": "string" }, "username": { "type": [ "string", "null" ] }, "storeName": { "type": "string" }, "vatPayer": { "type": "string", "enum": [ "customer", "merchant" ] }, "notifications": { "$ref": "#/components/schemas/NotificationPreferences" }, "isModerator": { "type": "boolean", "description": "Bu Telegram kimliğinin yapılandırılmış moderatör izin listesine ait olup olmadığı." } }, "required": [ "id", "displayName", "username", "storeName", "vatPayer", "notifications", "isModerator" ], "additionalProperties": false }, "UserResponse": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" } }, "required": [ "user" ], "additionalProperties": false }, "Anonymous": { "type": "object", "properties": { "authenticated": { "type": "boolean", "const": false } }, "required": [ "authenticated" ], "additionalProperties": false }, "CurrentSession": { "type": "object", "properties": { "authenticated": { "type": "boolean", "const": true }, "user": { "$ref": "#/components/schemas/User" }, "csrfToken": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." } }, "required": [ "authenticated", "user", "csrfToken", "expiresAt" ], "additionalProperties": false }, "LoginChallenge": { "type": "object", "properties": { "challengeId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "code": { "type": "string", "pattern": "^[0-9]{6}$" }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." }, "telegramUrl": { "type": "string", "format": "uri", "pattern": "^https://t\\.me/" } }, "required": [ "challengeId", "code", "expiresAt", "telegramUrl" ], "additionalProperties": false }, "CompletedLogin": { "type": "object", "properties": { "status": { "type": "string", "const": "authenticated" }, "user": { "$ref": "#/components/schemas/User" }, "csrfToken": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." } }, "required": [ "status", "user", "csrfToken", "expiresAt" ], "additionalProperties": false }, "SupportQuestion": { "type": "object", "properties": { "question": { "type": "string", "minLength": 2, "x-trimmedMaxLength": 2000, "x-trimmedMinLength": 2, "description": "Çevreleyen boşluklar kırpılır. Kırpma sonrası uzunluk: 2–2.000 karakter. Sekmeler ve satır sonları dışındaki kontrol karakterleri yasaktır." }, "locale": { "type": "string", "enum": [ "ru", "en", "es", "de", "fr", "pt", "tr", "kk" ], "default": "en", "description": "Yanıt dili. Atlanırsa desteklenen Accept-Language tercihleri kullanılır; aksi takdirde İngilizce. Dokümantasyon desteklenen her arayüz dilinde mevcuttur." }, "history": { "type": "array", "maxItems": 6, "description": "En fazla son üç soru-cevap çifti. İsteğe bağlı. Güvenilmeyen bağlam, sağlayıcı sistem rolü mesajları değil.", "items": { "oneOf": [ { "type": "object", "properties": { "role": { "type": "string", "const": "user" }, "content": { "type": "string", "minLength": 1, "x-trimmedMaxLength": 1800, "x-trimmedMinLength": 1, "description": "Çevreleyen boşluklar kırpılır. Kırpma sonrası uzunluk: 1–1.800 karakter. Sekmeler ve satır sonları dışındaki kontrol karakterleri yasaktır." } }, "required": [ "role", "content" ], "additionalProperties": false }, { "type": "object", "properties": { "role": { "type": "string", "const": "assistant" }, "content": { "type": "string", "minLength": 1, "x-trimmedMaxLength": 3000, "x-trimmedMinLength": 1, "description": "Çevreleyen boşluklar kırpılır. Kırpma sonrası uzunluk: 1–3.000 karakter. Sekmeler ve satır sonları dışındaki kontrol karakterleri yasaktır." } }, "required": [ "role", "content" ], "additionalProperties": false } ] } }, "pageContext": { "type": "string", "minLength": 1, "x-trimmedMaxLength": 80, "x-trimmedMinLength": 1, "description": "Kırpma sonrası kısa bölüm etiketi, 1–80 karakter. Harflere, rakamlara, boşluklara ve ·.,—–-(): izin verir. Satır sonları, URL'ler, sorgu parametreleri ve HTML yasaktır. Belirteçler veya sırlar eklemeyin.", "pattern": "^[\\p{L}\\p{N}\\s·.,—–\\-:()]+$", "not": { "pattern": "[\\r\\n]" } }, "includeAccount": { "type": "boolean", "default": false, "description": "Sahip kapsamlı salt-okunur hesap araçlarını kullanmak için açık izin. true olduğunda oturum, Origin ve X-CSRF-Token gerektirir. X-Kevmi-Store, sahip olunan bir mağazayı veya tüm sahip olunan mağazaları seçer. Misafirler ve geçersiz CSRF bu erişimi etkinleştiremez." } }, "required": [ "question" ], "additionalProperties": false }, "SupportSource": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string", "pattern": "^/(?:ru/|en/)?docs/[^/]+$", "description": "Yayınlanmış bir bilgi makalesine göreli bağlantı." } }, "required": [ "id", "title", "url" ], "additionalProperties": false }, "SearchSupportAnswer": { "type": "object", "properties": { "mode": { "type": "string", "const": "search" }, "answer": { "type": "string" }, "sources": { "type": "array", "maxItems": 3, "items": { "$ref": "#/components/schemas/SupportSource" } }, "knowledgeVersion": { "type": [ "string", "null" ] }, "needsHuman": { "type": "boolean" }, "aiUnavailable": { "type": "boolean", "const": true } }, "required": [ "mode", "answer", "sources", "knowledgeVersion", "needsHuman" ], "additionalProperties": false }, "AISupportAnswer": { "type": "object", "properties": { "mode": { "type": "string", "const": "ai" }, "answer": { "type": "string", "minLength": 1, "maxLength": 6000, "description": "Yalnızca düz metin; URL'ler ve HTML reddedilir. Bağlantılar yalnızca kaynaklarda döndürülür." }, "sources": { "type": "array", "maxItems": 25, "uniqueItems": true, "items": { "$ref": "#/components/schemas/SupportSource" } }, "knowledgeVersion": { "type": "string" }, "needsHuman": { "type": "boolean" } }, "required": [ "mode", "answer", "sources", "knowledgeVersion", "needsHuman" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "needsHuman": { "const": false } } }, "then": { "properties": { "sources": { "minItems": 1 } } } } ] }, "SupportAnswer": { "oneOf": [ { "$ref": "#/components/schemas/SearchSupportAnswer" }, { "$ref": "#/components/schemas/AISupportAnswer" } ] }, "Ticket": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^tkt_[a-f0-9-]{36}$" }, "subject": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "answered", "closed" ], "description": "answered, yanıtlanmış bir isteği belirtir. Genel API, bir kullanıcının yalnızca kendi isteğini kapatmasına izin verir." }, "source": { "type": "string", "enum": [ "web", "telegram" ] }, "createdAt": { "type": "integer", "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." }, "updatedAt": { "type": "integer", "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." }, "replies": { "type": "array", "items": { "$ref": "#/components/schemas/SupportReply" } } }, "required": [ "id", "subject", "message", "status", "source", "createdAt", "updatedAt" ], "additionalProperties": false }, "TicketResponse": { "type": "object", "properties": { "ticket": { "$ref": "#/components/schemas/Ticket" }, "replies": { "type": "array", "items": { "$ref": "#/components/schemas/SupportReply" } } }, "required": [ "ticket" ], "additionalProperties": false }, "Notification": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^ntf_[A-Za-z0-9-]{1,80}$" }, "kind": { "type": "string", "enum": [ "payments", "payouts", "support", "security", "test" ] }, "message": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "sending", "sent", "failed" ], "description": "Telegram teslimat durumu, web sitesi okuma durumundan bağımsızdır." }, "createdAt": { "type": "integer", "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." }, "sentAt": { "type": [ "integer", "null" ], "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." }, "readAt": { "type": [ "integer", "null" ], "minimum": 0, "description": "Web sitesinde ilk okuma zamanı; null okunmamış anlamına gelir. Bu, Telegram'da okunduğunu doğrulamaz." } }, "required": [ "id", "kind", "message", "status", "createdAt", "sentAt", "readAt" ], "additionalProperties": false }, "NotificationsPage": { "type": "object", "properties": { "notifications": { "type": "array", "maxItems": 30, "items": { "$ref": "#/components/schemas/Notification" } }, "unreadCount": { "type": "integer", "minimum": 0 }, "nextCursor": { "type": [ "string", "null" ], "description": "Sonraki sayfa imleci; başka kayıt kalmadıysa null." } }, "required": [ "notifications", "unreadCount", "nextCursor" ], "additionalProperties": false }, "ReadNotifications": { "oneOf": [ { "type": "object", "properties": { "ids": { "type": "array", "minItems": 1, "maxItems": 100, "description": "Yinelenenlere izin verilir ve bir kez sayılır.", "items": { "type": "string", "pattern": "^ntf_[A-Za-z0-9-]{1,80}$" } } }, "required": [ "ids" ], "additionalProperties": false }, { "type": "object", "properties": { "all": { "type": "boolean", "const": true }, "before": { "type": "integer", "minimum": 0, "description": "Görüntülenen son olayın createdAt değeri. Sunucu ayrıca before <= Date.now() olmasını gerektirir.", "maximum": 9007199254740991 } }, "required": [ "all", "before" ], "additionalProperties": false } ] }, "ReadNotificationsResult": { "type": "object", "properties": { "updated": { "type": "integer", "minimum": 0 }, "readAt": { "type": "integer", "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." }, "unreadCount": { "type": "integer", "minimum": 0 } }, "required": [ "updated", "readAt", "unreadCount" ], "additionalProperties": false }, "TelegramUpdate": { "type": "object", "properties": { "update_id": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "message": { "type": "object", "additionalProperties": true, "description": "Telegram Mesajı: işleyici message_id, text, from ve chat kullanır." }, "callback_query": { "type": "object", "additionalProperties": true, "description": "Telegram CallbackQuery: işleyici id, from, data ve message.chat kullanır." } }, "required": [ "update_id" ], "additionalProperties": true }, "IncomingQuote": { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "baseMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "grossMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "percentageFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "fixedFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "nominalFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "feeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "vatMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "customerVatMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "merchantVatMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "customerTotalMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "merchantDeductionMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "totalFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "netMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "currency": { "type": "string", "enum": [ "USD", "RUB", "USDT" ], "description": "Fatura birimleri: USD cent, RUB kopek veya USDT'nin yüzde biri. Otomatik para birimi dönüşümü yok." }, "method": { "type": "string", "enum": [ "card", "alipay", "sbp", "crypto" ] }, "vatPayer": { "type": "string", "enum": [ "customer", "merchant", "shared" ] }, "vatApplies": { "type": "boolean" }, "pricingVersion": { "type": "integer", "minimum": 1, "description": "Fatura ile kaydedilen hesaplama sürümü." }, "vatCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Müşteri payı, tam yüzde olarak. 0, satıcının her şeyi karşıladığı anlamına gelir; 100, müşterinin her şeyi karşıladığı anlamına gelir. Varsayılan: mağazanın eski KDV tercihi." }, "feeCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Müşteri payı, tam yüzde olarak. 0, satıcının her şeyi karşıladığı anlamına gelir; 100, müşterinin her şeyi karşıladığı anlamına gelir.", "default": 0 }, "customerFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "merchantFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "settlement": { "$ref": "#/components/schemas/SettlementQuote" } }, "required": [ "amountMinor", "baseMinor", "grossMinor", "percentageFeeMinor", "fixedFeeMinor", "nominalFeeMinor", "feeMinor", "vatMinor", "customerVatMinor", "merchantVatMinor", "customerTotalMinor", "merchantDeductionMinor", "totalFeeMinor", "netMinor", "currency", "method", "vatPayer", "vatApplies", "pricingVersion" ], "additionalProperties": false }, "PaymentLink": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^lnk_[0-9a-f-]{36}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "maxLength": 500 }, "merchantName": { "type": "string" }, "amountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "currency": { "type": "string", "enum": [ "USD", "RUB", "USDT" ], "description": "Fatura birimleri: USD cent, RUB kopek veya USDT'nin yüzde biri. Otomatik para birimi dönüşümü yok." }, "vatPayer": { "type": "string", "enum": [ "customer", "merchant", "shared" ] }, "methods": { "type": "array", "minItems": 1, "maxItems": 3, "uniqueItems": true, "items": { "type": "string", "enum": [ "card", "alipay", "sbp", "crypto" ] } }, "quotes": { "type": "object", "properties": { "card": { "$ref": "#/components/schemas/IncomingQuote" }, "alipay": { "$ref": "#/components/schemas/IncomingQuote" }, "sbp": { "$ref": "#/components/schemas/IncomingQuote" }, "crypto": { "$ref": "#/components/schemas/IncomingQuote" } }, "required": [], "additionalProperties": false }, "status": { "type": "string", "enum": [ "active", "paused", "expired", "cancelled" ], "description": "expired, okumada expiresAt'ten türetilir. cancelled kesindir." }, "createdAt": { "type": "integer", "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." }, "updatedAt": { "type": "integer", "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." }, "url": { "type": "string", "format": "uri", "description": "APP_ORIGIN üzerinde herkese açık /pay/{token} sayfası." }, "vatCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Müşteri payı, tam yüzde olarak. 0, satıcının her şeyi karşıladığı anlamına gelir; 100, müşterinin her şeyi karşıladığı anlamına gelir. Varsayılan: mağazanın eski KDV tercihi." }, "feeCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Müşteri payı, tam yüzde olarak. 0, satıcının her şeyi karşıladığı anlamına gelir; 100, müşterinin her şeyi karşıladığı anlamına gelir.", "default": 0 }, "orderId": { "type": "string", "maxLength": 100, "description": "Alıcının gördüğü sipariş referansı." }, "metadata": { "type": "object", "maxProperties": 10, "propertyNames": { "pattern": "^[A-Za-z0-9_-]{1,40}$" }, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Özel satıcı meta verileri. JSON serileştirmesinden sonra en fazla 3000 UTF-8 bayt. Herkese açık ödeme sayfasında asla gösterilmez." }, "checkoutUrl": { "type": "string", "format": "uri" }, "payment": { "oneOf": [ { "$ref": "#/components/schemas/PaymentSummary" }, { "type": "null" } ], "description": "Sahip listesi/detay GET isteklerine dahil edilir. Fatura yaşam döngüsü doğrulanmış ödeme durumundan bağımsızdır. Kart, banka kodu, QR veya alıcı ayrıntılarını içermez." }, "storeId": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "pricingMode": { "type": "string", "enum": [ "native", "universal" ] }, "fx": { "oneOf": [ { "$ref": "#/components/schemas/ExchangeRate" }, { "type": "null" } ] }, "usdtPerUsd": { "type": [ "string", "null" ] } }, "required": [ "id", "title", "description", "merchantName", "amountMinor", "currency", "vatPayer", "methods", "quotes", "status", "createdAt", "updatedAt", "expiresAt", "url", "vatCustomerPercent", "feeCustomerPercent", "orderId", "metadata", "checkoutUrl" ], "additionalProperties": false }, "CreatePaymentLink": { "oneOf": [ { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "x-trimmedMaxLength": 120, "x-trimmedMinLength": 1, "description": "Çevreleyen boşluklar kırpılır. Kırpmadan sonra uzunluk: 1-120 karakter. Sekmeler ve satır sonları dışındaki kontrol karakterleri yasaktır." }, "description": { "type": "string", "x-trimmedMaxLength": 500, "description": "İsteğe bağlı; boş dizeye izin verilir. Kırpmadan sonra en fazla 500 karakter." }, "amountMinor": { "type": "integer", "minimum": 1, "maximum": 10000000000, "description": "Teknik tamsayı sınırı, ticari sağlayıcı sınırı değil. Negatif satıcı kredisi reddedilir." }, "vatPayer": { "type": "string", "enum": [ "customer", "merchant" ], "description": "Atlandığında, mevcut mağazanın kuralı kaydedilir." }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Gelecekte bir zaman, oluşturmadan en fazla 90 gün sonra. Varsayılan yedi gündür. Fatura anlık görüntüsünde kaydedilir." }, "currency": { "type": "string", "const": "USD" }, "methods": { "type": "array", "minItems": 1, "maxItems": 3, "uniqueItems": true, "items": { "type": "string", "enum": [ "card", "alipay", "crypto" ] }, "description": "Yeni USD ödeme, kart ve Alipay destekler. USD kripto faturaları yalnızca uyumluluk için kabul edilir ve canlı ödemede crypto_requires_usdt döndürür; kripto için USDT kullanın." }, "vatCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Müşteri payı, tam yüzde olarak. 0, satıcının her şeyi karşıladığı anlamına gelir; 100, müşterinin her şeyi karşıladığı anlamına gelir. Varsayılan: mağazanın eski KDV tercihi." }, "feeCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Müşteri payı, tam yüzde olarak. 0, satıcının her şeyi karşıladığı anlamına gelir; 100, müşterinin her şeyi karşıladığı anlamına gelir.", "default": 0 }, "orderId": { "type": "string", "maxLength": 100, "description": "Alıcının gördüğü sipariş referansı." }, "metadata": { "type": "object", "maxProperties": 10, "propertyNames": { "pattern": "^[A-Za-z0-9_-]{1,40}$" }, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Özel satıcı meta verileri. JSON serileştirmesinden sonra en fazla 3000 UTF-8 bayt. Herkese açık ödeme sayfasında asla gösterilmez." }, "pricingMode": { "type": "string", "const": "native", "description": "Eski para birimine özgü fiyatlandırma. Mevcut entegrasyonlarla uyumluluk için atlayın." } }, "required": [ "title", "amountMinor", "currency", "methods" ], "additionalProperties": false }, { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "x-trimmedMaxLength": 120, "x-trimmedMinLength": 1, "description": "Çevreleyen boşluklar kırpılır. Kırpmadan sonra uzunluk: 1-120 karakter. Sekmeler ve satır sonları dışındaki kontrol karakterleri yasaktır." }, "description": { "type": "string", "x-trimmedMaxLength": 500, "description": "İsteğe bağlı; boş dizeye izin verilir. Kırpmadan sonra en fazla 500 karakter." }, "amountMinor": { "type": "integer", "minimum": 1, "maximum": 10000000000, "description": "Teknik tamsayı sınırı, ticari sağlayıcı sınırı değil. Negatif satıcı kredisi reddedilir." }, "vatPayer": { "type": "string", "enum": [ "customer", "merchant" ], "description": "Atlandığında, mevcut mağazanın kuralı kaydedilir." }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Gelecekte bir zaman, oluşturmadan en fazla 90 gün sonra. Varsayılan yedi gündür. Fatura anlık görüntüsünde kaydedilir." }, "currency": { "type": "string", "const": "RUB" }, "methods": { "type": "array", "minItems": 1, "maxItems": 1, "uniqueItems": true, "items": { "type": "string", "const": "sbp" } }, "vatCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Müşteri payı, tam yüzde olarak. 0, satıcının her şeyi karşıladığı anlamına gelir; 100, müşterinin her şeyi karşıladığı anlamına gelir. Varsayılan: mağazanın eski KDV tercihi." }, "feeCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Müşteri payı, tam yüzde olarak. 0, satıcının her şeyi karşıladığı anlamına gelir; 100, müşterinin her şeyi karşıladığı anlamına gelir.", "default": 0 }, "orderId": { "type": "string", "maxLength": 100, "description": "Alıcının gördüğü sipariş referansı." }, "metadata": { "type": "object", "maxProperties": 10, "propertyNames": { "pattern": "^[A-Za-z0-9_-]{1,40}$" }, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Özel satıcı meta verileri. JSON serileştirmesinden sonra en fazla 3000 UTF-8 bayt. Herkese açık ödeme sayfasında asla gösterilmez." }, "pricingMode": { "type": "string", "const": "native", "description": "Eski para birimine özgü fiyatlandırma. Mevcut entegrasyonlarla uyumluluk için atlayın." } }, "required": [ "title", "amountMinor", "currency", "methods" ], "additionalProperties": false }, { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "x-trimmedMaxLength": 120, "x-trimmedMinLength": 1, "description": "Çevreleyen boşluklar kırpılır. Kırpmadan sonra uzunluk: 1-120 karakter. Sekmeler ve satır sonları dışındaki kontrol karakterleri yasaktır." }, "description": { "type": "string", "x-trimmedMaxLength": 500, "description": "İsteğe bağlı; boş dizeye izin verilir. Kırpmadan sonra en fazla 500 karakter." }, "amountMinor": { "type": "integer", "minimum": 1, "maximum": 10000000000, "description": "Teknik tamsayı sınırı, ticari sağlayıcı sınırı değil. Negatif satıcı kredisi reddedilir." }, "vatPayer": { "type": "string", "enum": [ "customer", "merchant" ], "description": "Atlandığında, mevcut mağazanın kuralı kaydedilir." }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Gelecekte bir zaman, oluşturmadan en fazla 90 gün sonra. Varsayılan yedi gündür. Fatura anlık görüntüsünde kaydedilir." }, "currency": { "type": "string", "const": "USDT" }, "methods": { "type": "array", "minItems": 1, "maxItems": 1, "uniqueItems": true, "items": { "type": "string", "const": "crypto" } }, "vatCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Müşteri payı, tam yüzde olarak. 0, satıcının her şeyi karşıladığı anlamına gelir; 100, müşterinin her şeyi karşıladığı anlamına gelir. Varsayılan: mağazanın eski KDV tercihi." }, "feeCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Müşteri payı, tam yüzde olarak. 0, satıcının her şeyi karşıladığı anlamına gelir; 100, müşterinin her şeyi karşıladığı anlamına gelir.", "default": 0 }, "orderId": { "type": "string", "maxLength": 100, "description": "Alıcının gördüğü sipariş referansı." }, "metadata": { "type": "object", "maxProperties": 10, "propertyNames": { "pattern": "^[A-Za-z0-9_-]{1,40}$" }, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Özel satıcı meta verileri. JSON serileştirmesinden sonra en fazla 3000 UTF-8 bayt. Herkese açık ödeme sayfasında asla gösterilmez." }, "pricingMode": { "type": "string", "const": "native", "description": "Eski para birimine özgü fiyatlandırma. Mevcut entegrasyonlarla uyumluluk için atlayın." } }, "required": [ "title", "amountMinor", "currency", "methods" ], "additionalProperties": false }, { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "x-trimmedMaxLength": 120, "x-trimmedMinLength": 1, "description": "Çevreleyen boşluklar kırpılır. Kırpmadan sonra uzunluk: 1-120 karakter. Sekmeler ve satır sonları dışındaki kontrol karakterleri yasaktır." }, "description": { "type": "string", "x-trimmedMaxLength": 500, "description": "İsteğe bağlı; boş dizeye izin verilir. Kırpmadan sonra en fazla 500 karakter." }, "amountMinor": { "type": "integer", "minimum": 1, "maximum": 10000000000, "description": "Teknik tamsayı sınırı, ticari sağlayıcı sınırı değil. Negatif satıcı kredisi reddedilir." }, "vatPayer": { "type": "string", "enum": [ "customer", "merchant" ], "description": "Atlandığında, mevcut mağazanın kuralı kaydedilir." }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Gelecekte bir zaman, oluşturmadan en fazla 90 gün sonra. Varsayılan yedi gündür. Fatura anlık görüntüsünde kaydedilir." }, "currency": { "type": "string", "enum": [ "USD", "RUB", "USDT" ], "description": "Girdi birimi. RUB, kaydedilmiş referans kuru üzerinden USD'ye çevrilir; USDT açık 1:1 fatura kuralını kullanır. Kaydedilmiş fatura taban para birimi USD'dir." }, "methods": { "type": "array", "minItems": 1, "maxItems": 4, "uniqueItems": true, "items": { "type": "string", "enum": [ "card", "alipay", "sbp", "crypto" ] } }, "vatCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Müşteri payı, tam yüzde olarak. 0, satıcının her şeyi karşıladığı anlamına gelir; 100, müşterinin her şeyi karşıladığı anlamına gelir. Varsayılan: mağazanın eski KDV tercihi." }, "feeCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Müşteri payı, tam yüzde olarak. 0, satıcının her şeyi karşıladığı anlamına gelir; 100, müşterinin her şeyi karşıladığı anlamına gelir.", "default": 0 }, "orderId": { "type": "string", "maxLength": 100, "description": "Alıcının gördüğü sipariş referansı." }, "metadata": { "type": "object", "maxProperties": 10, "propertyNames": { "pattern": "^[A-Za-z0-9_-]{1,40}$" }, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Özel satıcı meta verileri. JSON serileştirmesinden sonra en fazla 3000 UTF-8 bayt. Herkese açık ödeme sayfasında asla gösterilmez." }, "pricingMode": { "type": "string", "const": "universal" } }, "required": [ "title", "amountMinor", "currency", "methods", "pricingMode" ], "additionalProperties": false } ], "description": "Tutarlar alt birimler kullanır. Ücret ve KDV, taban sipariş tutarı üzerinden hesaplanır. Müşteri payı yukarı yuvarlanır; satıcı tam kalanı karşılar. Çakışan eski vatPayer ve vatCustomerPercent değeri reddedilir. Tahsis, oluşturmadan sonra değişmezdir; değiştirmek için yeni bir fatura düzenleyin. Canlı kart/Alipay, vatCustomerPercent=100 ve feeCustomerPercent=0 gerektirir çünkü yapılandırılmış ağ geçidi özel vergisini geçersiz kılamaz. Diğer kaydedilmiş tahsisler unsupported_allocation döndürür; asla sessizce değiştirilmez. SBP ve USDT kripto ücret tahsisini destekler. Ödeme bilgilerini toplamadan önce genel fatura kullanılabilirlik nesnesini kullanın. Evrensel mod, USD taban fiyat ve ayrı yerel tahsil kotasyonları saklar: kartlar/Alipay için USD, SBP için RUB, kripto için USDT. RUB dönüştürmesi kaydedilmiş Rusya Merkez Bankası referans kurunu kullanır. Kripto, piyasa kotasyonu değil, açık fatura kuralı 1 USD = 1 USDT kullanır. RUB dönüştürmesi içeren faturalar, expiresAt daha sonraki bir tarih talep etse bile 24 saatle sınırlıdır. FX kaynağı hatası 503 FX_UNAVAILABLE döndürür. Eski yerel davranış için pricingMode'u atlayın.", "examples": [ { "pricingMode": "universal", "title": "Sipariş 1042", "amountMinor": 1000, "currency": "USD", "methods": [ "card", "alipay", "sbp", "crypto" ], "vatCustomerPercent": 100, "feeCustomerPercent": 0 }, { "title": "Sipariş 1042", "amountMinor": 500, "currency": "USD", "methods": [ "card", "alipay" ], "vatCustomerPercent": 100, "feeCustomerPercent": 0, "orderId": "1042" }, { "title": "Sipariş 1043", "amountMinor": 1000, "currency": "USDT", "methods": [ "crypto" ], "feeCustomerPercent": 23, "orderId": "1043" } ] }, "PaymentLinkResponse": { "type": "object", "properties": { "link": { "$ref": "#/components/schemas/PaymentLink" }, "checkoutUrl": { "type": "string", "format": "uri", "description": "Durum güncelleme yanıtlarına dahil edilir; iç içe bağlantı her zaman checkoutUrl'sini içerir." } }, "required": [ "link" ], "additionalProperties": false }, "CreatePaymentLinkResponse": { "type": "object", "properties": { "link": { "$ref": "#/components/schemas/PaymentLink" }, "replayed": { "type": "boolean" }, "checkoutUrl": { "type": "string", "format": "uri", "description": "Ödeme bağlantısı hemen kullanılabilir; yoklama gerekmez." } }, "required": [ "link", "replayed", "checkoutUrl" ], "additionalProperties": false }, "PaymentLinksPage": { "type": "object", "properties": { "links": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/PaymentLink" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Opak sonraki sayfa imleci. URL kodlu bir sorgu parametresi olarak iletin; null sonu işaretler." } }, "required": [ "links", "nextCursor" ], "additionalProperties": false }, "CheckoutQuote": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "card", "alipay", "sbp", "crypto" ] }, "amountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "vatMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "customerVatMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "customerTotalMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "vatApplies": { "type": "boolean" }, "pricingVersion": { "type": "integer", "minimum": 1, "description": "Fatura ile kaydedilen hesaplama sürümü." }, "customerFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "merchantCoveredMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." } }, "required": [ "method", "amountMinor", "vatMinor", "customerVatMinor", "customerTotalMinor", "vatApplies", "pricingVersion", "customerFeeMinor", "merchantCoveredMinor" ], "additionalProperties": false }, "CheckoutInvoice": { "type": "object", "properties": { "token": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "title": { "type": "string" }, "description": { "type": "string" }, "merchantName": { "type": "string" }, "amountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "currency": { "type": "string", "enum": [ "USD", "RUB", "USDT" ], "description": "Fatura birimleri: USD cent, RUB kopek veya USDT'nin yüzde biri. Otomatik para birimi dönüşümü yok." }, "vatPayer": { "type": "string", "enum": [ "customer", "merchant", "shared" ] }, "methods": { "type": "array", "minItems": 1, "maxItems": 3, "items": { "type": "string", "enum": [ "card", "alipay", "sbp", "crypto" ] } }, "status": { "type": "string", "enum": [ "active", "paused", "expired", "cancelled" ], "description": "expired, okumada expiresAt'ten türetilir. cancelled kesindir." }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." }, "createdAt": { "type": "integer", "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." }, "quote": { "$ref": "#/components/schemas/CheckoutQuote" }, "gatewayConnected": { "type": "boolean", "description": "availability.available için uyumluluk takma adı, ağ geçidi sağlık yoklaması değil." }, "vatCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Müşteri payı, tam yüzde olarak. 0, satıcının her şeyi karşıladığı anlamına gelir; 100, müşterinin her şeyi karşıladığı anlamına gelir. Varsayılan: mağazanın eski KDV tercihi." }, "feeCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Müşteri payı, tam yüzde olarak. 0, satıcının her şeyi karşıladığı anlamına gelir; 100, müşterinin her şeyi karşıladığı anlamına gelir.", "default": 0 }, "orderId": { "type": "string", "maxLength": 100, "description": "Alıcının gördüğü sipariş referansı." }, "availability": { "$ref": "#/components/schemas/CheckoutAvailability" }, "baseAmountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "baseCurrency": { "type": "string", "enum": [ "USD", "RUB", "USDT" ] }, "fx": { "oneOf": [ { "$ref": "#/components/schemas/ExchangeRate" }, { "type": "null" } ] }, "usdtPerUsd": { "type": [ "string", "null" ] } }, "required": [ "token", "title", "description", "merchantName", "amountMinor", "currency", "vatPayer", "methods", "status", "expiresAt", "createdAt", "quote", "gatewayConnected", "vatCustomerPercent", "feeCustomerPercent", "orderId", "availability" ], "additionalProperties": false }, "MerchantKey": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^key_[0-9a-f-]{36}$" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "scopes": { "type": "array", "minItems": 1, "maxItems": 3, "uniqueItems": true, "items": { "type": "string", "enum": [ "invoices:read", "invoices:write", "events:read" ] } }, "createdAt": { "type": "integer", "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." }, "revokedAt": { "type": [ "integer", "null" ], "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." }, "lastUsedAt": { "type": [ "integer", "null" ], "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." }, "storeId": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" } }, "required": [ "id", "name", "prefix", "scopes", "createdAt", "expiresAt" ], "additionalProperties": false }, "MerchantEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[a-f0-9]{40}$" }, "type": { "type": "string", "enum": [ "invoice.created", "invoice.updated", "payment.succeeded", "payment.failed", "payment.refunded", "payment.partially_refunded", "payment.disputed", "payment.review_required" ] }, "apiVersion": { "type": "string", "const": "2026-10-21" }, "createdAt": { "type": "integer", "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." }, "livemode": { "type": "boolean" }, "data": { "type": "object", "additionalProperties": true, "description": "invoice.created/updated: özel meta veriler dahil kalıcı satıcı faturası. ödeme olayları: doğrulanmış ödeme gerçekleri. Örnekler için webhook kılavuzuna bakın." } }, "required": [ "id", "type", "apiVersion", "createdAt", "livemode", "data" ], "additionalProperties": false }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^wh_[0-9a-f-]{36}$" }, "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "invoice.created", "invoice.updated", "payment.succeeded", "payment.failed", "payment.refunded", "payment.partially_refunded", "payment.disputed", "payment.review_required" ] } }, "status": { "type": "string", "enum": [ "unverified", "active", "paused" ] }, "createdAt": { "type": "integer", "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." }, "verifiedAt": { "type": [ "integer", "null" ], "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." }, "storeId": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" } }, "required": [ "id", "url", "description", "events", "status", "createdAt", "verifiedAt" ], "additionalProperties": false }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string" }, "event_id": { "type": "string" }, "endpoint_id": { "type": "string" }, "type": { "type": "string", "enum": [ "invoice.created", "invoice.updated", "payment.succeeded", "payment.failed", "payment.refunded", "payment.partially_refunded", "payment.disputed", "payment.review_required" ] }, "status": { "type": "string", "enum": [ "pending", "sending", "delivered", "failed", "cancelled" ] }, "attempts": { "type": "integer", "minimum": 0, "maximum": 6 }, "next_attempt_at": { "type": "integer", "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." }, "last_status": { "type": [ "integer", "null" ] }, "last_error": { "type": [ "string", "null" ] }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." }, "delivered_at": { "type": [ "integer", "null" ], "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." } }, "required": [ "id", "event_id", "endpoint_id", "type", "status", "attempts" ], "additionalProperties": false }, "Application": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^app_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "websiteUrl": { "type": "string", "format": "uri", "maxLength": 2048 }, "businessName": { "type": "string", "minLength": 1, "maxLength": 100 }, "businessType": { "type": "string", "enum": [ "digital_goods", "software", "services", "physical_goods", "education", "other" ] }, "description": { "type": "string", "minLength": 40, "maxLength": 3000 }, "contactTelegram": { "type": "string", "pattern": "^@[A-Za-z][A-Za-z0-9_]{4,31}$" }, "status": { "type": "string", "enum": [ "processing", "needs_review", "approved", "rejected" ] }, "currentStage": { "type": "string", "enum": [ "received", "ai_review", "technical_review", "manual_review" ] }, "version": { "type": "integer", "minimum": 1 }, "reason": { "type": "string", "description": "Kullanıcıya dönük aşama mesajı veya moderatör tarafından düzenlenmiş reddetme nedeni. Dahili kanıt hariç tutulur." }, "createdAt": { "type": "integer", "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." }, "updatedAt": { "type": "integer", "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." }, "stages": { "type": "array", "minItems": 4, "maxItems": 4, "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "received", "ai_review", "technical_review", "manual_review" ] }, "state": { "type": "string", "enum": [ "pending", "running", "complete", "review", "rejected" ] }, "message": { "type": "string" }, "updatedAt": { "type": [ "integer", "null" ], "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." } }, "required": [ "id", "state", "message", "updatedAt" ], "additionalProperties": false } }, "url": { "type": "string", "format": "uri", "description": "Özel, açık yerel ayar izleme URL'si. URL'yi bilmek erişim vermez." }, "notificationCategory": { "type": "string", "const": "support" }, "canResume": { "type": "boolean" }, "storeId": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" } }, "required": [ "id", "websiteUrl", "businessName", "businessType", "description", "contactTelegram", "status", "currentStage", "version", "reason", "createdAt", "updatedAt", "stages", "url", "notificationCategory", "canResume" ], "additionalProperties": false }, "ApplicationEvent": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 1 }, "stage": { "type": "string", "enum": [ "received", "ai_review", "technical_review", "manual_review" ] }, "state": { "type": "string", "enum": [ "pending", "running", "complete", "review", "rejected" ] }, "message": { "type": "string" }, "createdAt": { "type": "integer", "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." } }, "required": [ "version", "stage", "state", "message", "createdAt" ], "additionalProperties": false }, "PaymentSummary": { "type": "object", "properties": { "id": { "type": "string", "description": "Bilindiğinde kurallı ağ geçidi ödeme kimliği; aksi takdirde yerel gwp_ işlem kimliği." }, "method": { "type": "string", "enum": [ "card", "alipay", "sbp", "crypto" ] }, "status": { "type": "string", "enum": [ "pending", "requires_action", "processing", "succeeded", "failed", "expired", "review_required", "partially_paid", "partially_refunded", "refunded", "disputed" ] }, "amountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "currency": { "type": "string", "enum": [ "USD", "RUB", "USDT" ], "description": "Fatura birimleri: USD cent, RUB kopek veya USDT'nin yüzde biri. Otomatik para birimi dönüşümü yok." }, "fulfillmentReady": { "type": "boolean" }, "updatedAt": { "type": "integer", "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." }, "refundedAmountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." } }, "required": [ "id", "method", "status", "amountMinor", "currency", "fulfillmentReady", "updatedAt" ], "additionalProperties": false }, "CheckoutAvailability": { "type": "object", "properties": { "available": { "type": "boolean" }, "code": { "type": "string", "enum": [ "ready", "not_configured", "unsupported_allocation", "crypto_requires_usdt", "amount_out_of_range", "merchant_not_approved" ] }, "flow": { "type": "string", "enum": [ "encrypted_card", "qr", "crypto" ] }, "minAmountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "maxAmountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "limitsSource": { "type": "string", "const": "adapter", "description": "Bu entegrasyon tarafından uygulanan muhafazakâr sınırlar, üst akış ticari sınırları hakkında bir iddia değil." } }, "required": [ "available", "code", "flow", "minAmountMinor", "maxAmountMinor", "limitsSource" ], "additionalProperties": false }, "CheckoutAction": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "redirect", "qr", "crypto" ] }, "url": { "type": [ "string", "null" ], "format": "uri" }, "qrImage": { "type": [ "string", "null" ] }, "qrPayload": { "type": [ "string", "null" ] }, "address": { "type": "string" }, "amount": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "description": "Seçilen coin'de tam transfer tutarı; yuvarlama veya kayan nokta dönüşümü olmadan ondalık dizeyi koruyun." }, "currency": { "type": "string" }, "network": { "type": "string" }, "networkLabel": { "type": "string" }, "expiresAt": { "type": [ "integer", "null" ], "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." }, "addressQrImage": { "type": [ "string", "null" ] }, "amountQrImage": { "type": [ "string", "null" ] }, "amountQrPayload": { "type": [ "string", "null" ] }, "networkFeePaidByCustomer": { "type": "boolean" } }, "required": [ "type", "expiresAt" ], "additionalProperties": false }, "CheckoutPayment": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^gwp_[0-9a-f-]{36}$" }, "method": { "type": "string", "enum": [ "card", "alipay", "sbp", "crypto" ] }, "status": { "type": "string", "enum": [ "pending", "requires_action", "processing", "succeeded", "failed", "expired", "review_required", "partially_paid", "partially_refunded", "refunded", "disputed" ] }, "providerStatus": { "type": "string" }, "fulfillmentReady": { "type": "boolean", "description": "Yalnızca tam tutar/para birimi/sipariş bağlama ve sağlayıcı tarafından onaylanmış başarı sonrasında true olur. Tarayıcı yönlendirmesi asla ödeme onayı değildir." }, "amountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "currency": { "type": "string", "enum": [ "USD", "RUB", "USDT" ], "description": "Fatura birimleri: USD cent, RUB kopek veya USDT'nin yüzde biri. Otomatik para birimi dönüşümü yok." }, "createdAt": { "type": "integer", "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." }, "updatedAt": { "type": "integer", "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." }, "nextAction": { "oneOf": [ { "$ref": "#/components/schemas/CheckoutAction" }, { "type": "null" } ] }, "expiresAt": { "type": [ "integer", "null" ], "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." }, "authentication": { "type": "object", "properties": { "required": { "type": "boolean" }, "expiresAt": { "type": [ "integer", "null" ], "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." }, "attempt": { "type": "integer", "minimum": 0 } }, "required": [ "required", "expiresAt", "attempt" ], "additionalProperties": false }, "reason": { "type": "string", "enum": [ "amount_mismatch", "confirmation_required", "refund_mismatch", "settlement_unverified" ] }, "refundedAmountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." } }, "required": [ "id", "method", "status", "providerStatus", "fulfillmentReady", "amountMinor", "currency", "createdAt", "updatedAt", "nextAction", "expiresAt" ], "additionalProperties": false }, "SealedCardData": { "type": "object", "properties": { "intent": { "type": "string", "minLength": 32, "maxLength": 8192, "description": "/card-intent'ten imzalanmış, kısa ömürlü işlem niyeti; değiştirilmeden iletin." }, "jwe": { "type": "string", "maxLength": 14000, "pattern": "^[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+){4}$", "description": "RSA-OAEP-256 ve A256GCM kullanan kompakt JWE. Korumalı başlık: genel anahtardan kid, typ=kevmi-card+jwe. Kevmi'ye yalnızca şifreli metin gönderilir. Düz metin kart veya banka kodu alanlarını asla göndermeyin." } }, "required": [ "intent", "jwe" ], "additionalProperties": false }, "CardIntent": { "type": "object", "properties": { "intent": { "type": "string", "minLength": 32, "maxLength": 8192 }, "intentId": { "type": "string", "maxLength": 100 }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." }, "key": { "type": "object", "properties": { "kid": { "type": "string" }, "kty": { "type": "string", "const": "RSA" }, "n": { "type": "string" }, "e": { "type": "string" }, "alg": { "type": "string", "const": "RSA-OAEP-256" }, "use": { "type": "string", "const": "enc" } }, "required": [ "kid", "kty", "n", "e", "alg", "use" ], "additionalProperties": false }, "algorithm": { "type": "string", "const": "RSA-OAEP-256" }, "encryption": { "type": "string", "const": "A256GCM" }, "protocol": { "type": "string", "const": "kevmi-card-v1" } }, "required": [ "intent", "intentId", "expiresAt", "key", "algorithm", "encryption", "protocol" ], "additionalProperties": false }, "StartCheckoutPayment": { "oneOf": [ { "type": "object", "properties": { "method": { "type": "string", "const": "card" }, "sealed": { "$ref": "#/components/schemas/SealedCardData" } }, "required": [ "method", "sealed" ], "additionalProperties": false }, { "type": "object", "properties": { "method": { "type": "string", "const": "alipay" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "country": { "type": "string", "const": "CN" }, "email": { "type": "string", "format": "email", "maxLength": 254 } }, "required": [ "method", "name", "country" ], "additionalProperties": false }, { "type": "object", "properties": { "method": { "type": "string", "const": "sbp" } }, "required": [ "method" ], "additionalProperties": false }, { "type": "object", "properties": { "method": { "type": "string", "const": "crypto" }, "payerCurrency": { "type": "string", "pattern": "^[A-Z0-9]{2,16}$" }, "network": { "type": "string", "pattern": "^[a-z0-9_-]{2,32}$" } }, "required": [ "method", "payerCurrency", "network" ], "additionalProperties": false } ] }, "LegacyGatewayEvent": { "type": "object", "properties": { "eventId": { "type": "string", "maxLength": 100, "pattern": "^[A-Za-z0-9_.:-]+$" }, "paymentId": { "type": "string", "maxLength": 100, "pattern": "^[A-Za-z0-9_.:-]+$" }, "invoiceId": { "type": "string", "pattern": "^lnk_[0-9a-f-]{36}$" }, "status": { "type": "string", "enum": [ "succeeded", "failed", "refunded" ] }, "amountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "currency": { "type": "string", "enum": [ "USD", "RUB", "USDT" ], "description": "Fatura birimleri: USD cent, RUB kopek veya USDT'nin yüzde biri. Otomatik para birimi dönüşümü yok." }, "method": { "type": "string", "enum": [ "card", "alipay", "sbp", "crypto" ] }, "occurredAt": { "type": "integer", "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." } }, "required": [ "eventId", "paymentId", "invoiceId", "status", "amountMinor", "currency", "method", "occurredAt" ], "additionalProperties": false }, "NativeGatewayEvent": { "type": "object", "required": [ "id", "api_version", "mode", "type", "data" ], "properties": { "id": { "type": "string", "format": "uuid" }, "api_version": { "type": "string", "const": "3" }, "mode": { "type": "string", "const": "live" }, "type": { "type": "string", "pattern": "^[a-z_.]{1,80}$" }, "data": { "type": "object", "required": [ "id", "version" ], "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 0 }, "merchant_order_id": { "type": "string" } } } } }, "Store": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "vatPayer": { "type": "string", "enum": [ "customer", "merchant" ] }, "createdAt": { "type": "integer", "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." }, "updatedAt": { "type": "integer", "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." }, "reviewStatus": { "type": "string", "enum": [ "not_submitted", "processing", "needs_review", "approved", "rejected" ] }, "applicationId": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "vatPayer", "createdAt", "updatedAt", "reviewStatus", "applicationId" ], "additionalProperties": false }, "ExchangeRate": { "type": "object", "properties": { "rubPerUsdMicros": { "type": "integer", "minimum": 1000000 }, "effectiveAt": { "type": "integer", "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." }, "fetchedAt": { "type": "integer", "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." }, "source": { "type": "string", "const": "https://www.cbr.ru/scripts/XML_daily.asp" }, "usdtPerUsd": { "type": "string", "const": "1.00" } }, "required": [ "rubPerUsdMicros", "effectiveAt", "fetchedAt", "source", "usdtPerUsd" ], "additionalProperties": false }, "SettlementQuote": { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "baseMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "grossMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "percentageFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "fixedFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "nominalFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "feeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "vatMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "customerVatMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "merchantVatMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "customerTotalMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "merchantDeductionMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "totalFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "netMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "currency": { "type": "string", "enum": [ "USD", "RUB", "USDT" ], "description": "Fatura birimleri: USD cent, RUB kopek veya USDT'nin yüzde biri. Otomatik para birimi dönüşümü yok." }, "method": { "type": "string", "enum": [ "card", "alipay", "sbp", "crypto" ] }, "vatPayer": { "type": "string", "enum": [ "customer", "merchant", "shared" ] }, "vatApplies": { "type": "boolean" }, "pricingVersion": { "type": "integer", "minimum": 1, "description": "Fatura ile kaydedilen hesaplama sürümü." }, "vatCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Müşteri payı, tam yüzde olarak. 0, satıcının her şeyi karşıladığı anlamına gelir; 100, müşterinin her şeyi karşıladığı anlamına gelir. Varsayılan: mağazanın eski KDV tercihi." }, "feeCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Müşteri payı, tam yüzde olarak. 0, satıcının her şeyi karşıladığı anlamına gelir; 100, müşterinin her şeyi karşıladığı anlamına gelir.", "default": 0 }, "customerFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." }, "merchantFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Küçük para birimi birimlerinde tamsayı tutar." } }, "required": [ "amountMinor", "baseMinor", "grossMinor", "percentageFeeMinor", "fixedFeeMinor", "nominalFeeMinor", "feeMinor", "vatMinor", "customerVatMinor", "merchantVatMinor", "customerTotalMinor", "merchantDeductionMinor", "totalFeeMinor", "netMinor", "currency", "method", "vatPayer", "vatApplies", "pricingVersion" ], "additionalProperties": false }, "SupportReply": { "type": "object", "properties": { "id": { "type": "string" }, "message": { "type": "string" }, "createdAt": { "type": "integer", "minimum": 0, "description": "Unix zaman damgası, milisaniye cinsinden, UTC." } }, "required": [ "id", "message", "createdAt" ], "additionalProperties": false } } }, "webhooks": { "merchantEvent": { "post": { "summary": "Doğrulanmış satıcı sunucusu teslimatı", "description": "Yalnızca etkin, istem doğrulamalı uç noktalara teslim edilir. Ham JSON imzalanır; ayrıştırmadan veya sipariş durumunu değiştirmeden önce zaman damgasını ve imzayı doğrulayın. Olayı kalıcı olarak kabul ettikten sonra 2xx döndürün. Yinelenenleri ele almak için olay kimliklerini kalıcı hale getirin. Ağ hataları, zaman aşımı ve 2xx olmayan durumlar yeniden denemeleri tetikler.", "parameters": [ { "name": "Kevmi-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Kevmi-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Kevmi-Delivery-Id", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "JSON nesnesi. En fazla 16.384 bayt. Bilinmeyen alanlar reddedilir.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantEvent" } } } }, "responses": { "2XX": { "description": "Satıcı sunucusu tarafından kalıcı olarak kabul edildi." } } } } } }