{
  "openapi": "3.1.0",
  "info": {
    "title": "KriptoGo API",
    "version": "1.0.0",
    "summary": "TRON ağında USDT (TRC-20) ve TRX ile kripto ödeme alma API'si",
    "description": "KriptoGo, web siteleri, SaaS ürünleri ve Telegram botları için kripto ödeme geçididir. İki uç nokta (fatura oluştur, durum sorgula) ve bir webhook ile entegre olur. Fatura oluşturma çağrısı yalnızca sunucu tarafından yapılmalıdır; apiKey tarayıcıya gönderilmez. Tam döküman: https://kriptogo.com/docs",
    "termsOfService": "https://kriptogo.com/#sss",
    "contact": { "name": "KriptoGo", "url": "https://kriptogo.com/dashboard" },
    "x-logo": { "url": "https://kriptogo.com/logo.png" }
  },
  "servers": [{ "url": "https://kriptogo.com", "description": "Üretim" }],
  "tags": [
    { "name": "Fatura", "description": "Ödeme talebi oluşturma ve durum sorgulama" },
    { "name": "Webhook", "description": "KriptoGo'nun satıcı sunucusuna gönderdiği bildirim" }
  ],
  "paths": {
    "/api/create-invoice": {
      "post": {
        "tags": ["Fatura"],
        "operationId": "createInvoice",
        "summary": "Fatura oluştur (yalnızca sunucudan)",
        "description": "Yeni bir ödeme talebi açar ve müşteriye özel TRON adresi ayırır. Yanıttaki checkout_url adresine müşteriyi yönlendirin. Fatura 10 dakika geçerlidir.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateInvoiceRequest" },
              "example": { "apiKey": "pk_...", "amount": 49.9, "callbackUrl": "https://siten.com/kriptogo-webhook", "returnUrl": "https://siten.com/tesekkurler" }
            }
          }
        },
        "responses": {
          "201": { "description": "Fatura oluşturuldu", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } },
          "400": { "description": "Eksik/geçersiz alan veya izin verilmeyen URL (yalnızca herkese açık https)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "403": { "description": "Hesap henüz onaylanmadı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "404": { "description": "API anahtarı bulunamadı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "429": { "description": "Çok fazla açık fatura veya istek", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "503": { "description": "Tüm ödeme adresleri kullanımda; kısa süre sonra tekrar deneyin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        },
        "security": [{ "apiKeyInBody": [] }]
      }
    },
    "/api/status/{invoice_id}": {
      "get": {
        "tags": ["Fatura"],
        "operationId": "getInvoiceStatus",
        "summary": "Fatura durumunu sorgula (herkese açık)",
        "description": "API anahtarı gerektirmez; ön yüzden de çağrılabilir. Ödeme sayfası bu ucu birkaç saniyede bir kullanır.",
        "parameters": [{ "name": "invoice_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": {
          "200": { "description": "Fatura durumu", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceStatus" } } } },
          "400": { "description": "Geçersiz kimlik biçimi" },
          "404": { "description": "Fatura bulunamadı" }
        }
      }
    }
  },
  "webhooks": {
    "paymentConfirmed": {
      "post": {
        "tags": ["Webhook"],
        "summary": "payment.confirmed — ödeme zincirde onaylandı",
        "description": "KriptoGo, faturadaki callbackUrl adresine (yoksa panelde kayıtlı webhook adresine) JSON POST gönderir. X-Kriptogo-Signature başlığı, ham istek gövdesinin satıcının secret key'i ile HMAC-SHA256 imzasıdır (hex). Sipariş onaylanmadan önce imza sabit zamanlı karşılaştırma ile doğrulanmalıdır. Başarısız teslimat 3 kez denenir; aynı invoice_id tekrar gelebilir, işleme idempotent olmalıdır. Uç nokta 10 saniye içinde 200 döndürmelidir.",
        "parameters": [
          { "name": "X-Kriptogo-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "HMAC-SHA256(ham gövde, secretKey), hex" },
          { "name": "X-Kriptogo-Signature-256", "in": "header", "schema": { "type": "string" }, "description": "Aynı imza, 'sha256=' önekli" }
        ],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } },
        "responses": { "200": { "description": "Satıcı bildirimi aldı" } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKeyInBody": { "type": "apiKey", "in": "query", "name": "apiKey", "description": "Anahtar istek gövdesinde (JSON) gönderilir. Yalnızca sunucu tarafında saklayın." }
    },
    "schemas": {
      "CreateInvoiceRequest": {
        "type": "object",
        "required": ["apiKey", "amount"],
        "properties": {
          "apiKey": { "type": "string", "description": "Paneldeki API anahtarı (pk_...)" },
          "amount": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000000, "description": "Tahsil edilecek tutar, USDT" },
          "callbackUrl": { "type": "string", "format": "uri", "description": "Bu faturaya özel webhook adresi (yalnızca herkese açık https)" },
          "returnUrl": { "type": "string", "format": "uri", "description": "Ödeme sonrası müşterinin yönlendirileceği adres" }
        }
      },
      "Invoice": {
        "type": "object",
        "properties": {
          "invoice_id": { "type": "string", "format": "uuid" },
          "address": { "type": "string", "description": "Müşterinin ödeme yapacağı TRON adresi" },
          "amount": { "type": "number" },
          "network": { "type": "string", "const": "TRON" },
          "status": { "type": "string", "enum": ["PENDING"] },
          "expires_at": { "type": "string", "format": "date-time" },
          "checkout_url": { "type": "string", "format": "uri", "description": "Hazır ödeme sayfası" }
        }
      },
      "InvoiceStatus": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "amount": { "type": "number", "description": "Fatura tutarı (USDT)" },
          "paidAmount": { "type": ["number", "null"], "description": "Zincirde gerçekte alınan tutar (USDT karşılığı)" },
          "address": { "type": "string" },
          "currency": { "type": "string", "enum": ["USDT", "TRX"] },
          "status": { "type": "string", "enum": ["PENDING", "PAID", "EXPIRED"] },
          "txHash": { "type": ["string", "null"] },
          "returnUrl": { "type": ["string", "null"] },
          "merchantName": { "type": ["string", "null"] },
          "createdAt": { "type": "string", "format": "date-time" },
          "expiresAt": { "type": "string", "format": "date-time" },
          "trxPrice": { "type": "number", "description": "1 TRX'in USD fiyatı" },
          "trxAmount": { "type": "number", "description": "TRX ile ödenecekse gereken miktar" }
        }
      },
      "WebhookPayload": {
        "type": "object",
        "properties": {
          "event": { "type": "string", "const": "payment.confirmed" },
          "invoice_id": { "type": "string", "format": "uuid" },
          "amount": { "type": "string", "description": "Fatura tutarı" },
          "paid_amount": { "type": "string", "description": "Gerçekte alınan tutar; siparişi onaylarken bununla karşılaştırın" },
          "currency": { "type": "string", "enum": ["USDT", "TRX"] },
          "address": { "type": "string" },
          "tx_hash": { "type": "string" },
          "status": { "type": "string", "const": "PAID" },
          "timestamp": { "type": "string", "format": "date-time" }
        }
      },
      "Error": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" } } }
    }
  },
  "externalDocs": { "description": "Tam döküman ve kod örnekleri", "url": "https://kriptogo.com/docs" }
}