Kod bloklarını seçip kopyalayabilirsiniz. Tüm /v1 çağrılarında X-Api-Key zorunludur.

Genel Bakış

Ana site, yatırım almak için bu API'yi sunucudan sunucuya çağırır. Akış:

Kullanıcı ana sitede tutarı yazar, "Para Yatır"a basar.
Ana sitenin sunucusu POST /v1/deposit-oturumlari ile oturum açar.
Dönen baglanti adresine kullanıcı yönlendirilir (deposit sayfası).
Kullanıcı bilgilendirmeyi okur, Devam Et'e basar, IBAN'a ödemeyi yapar, "Ödemeyi Yaptım"a basar.
Finans panelinde yatırım talebi oluşur; operatör onaylar veya reddeder.
Sonuç, yalnızca oturumu açan API anahtarının geri çağırma adresine imzalı olarak bildirilir. Ana site ayrıca durumu sorgulayabilir.

Kimlik Doğrulama

Tüm /v1 çağrılarında X-Api-Key başlığı zorunludur. Anahtar, finans panelindeki API Anahtarları sekmesinden üretilir. İsteğe bağlı olarak anahtara izinli sunucu adresi ve geri çağırma adresi tanımlanır.

X-Api-Key: fn_...

1. Oturum Açma

POST /v1/deposit-oturumlari
Content-Type: application/json
X-Api-Key: fn_...

{
  "kullanici_id": "u123",
  "kullanici_adi": "veli123",
  "ad_soyad": "Ahmet Yılmaz",
  "tutar": 1500,
  "harici_referans": "SIPARIS-9981",
  "idempotency_key": "dep-u123-9981"
}

Alan	Zorunlu	Açıklama
`kullanici_id`	Evet	Ana sitedeki tekil kullanıcı kimliği (eşleşmede esas alınır)
`kullanici_adi`	Evet	Görüntülenen kullanıcı adı
`ad_soyad`	Evet	Yatıran kişinin adı (deposit ekranında maskeli gösterilir)
`tutar`	Evet	Pozitif sayı; paneldeki en az/en çok limitleri arasında olmalı
`harici_referans`	Hayır	Ana sitedeki sipariş / işlem kimliği; yanıtta ve callback'te aynen döner
`idempotency_key`	Hayır	Aynı API anahtarı + anahtar çifti için yeniden gönderimde mevcut oturum döner (ağ kesintisi güvenliği)

Başarılı yanıt (201):

{
  "referans": "K7P2M9XQ4RTB",
  "durum": "acik",
  "tutar": 1500.0,
  "para_birimi": "TRY",
  "bitis_zamani": "2026-09-12T01:30:00Z",
  "harici_referans": "SIPARIS-9981",
  "baglanti": "https://deposit.ornek.com/d/K7P2M9XQ4RTB"
}

Kullanıcıyı baglanti adresine yönlendirin. Oturum süresi varsayılan 10 dakikadır ve sunucuda uygulanır.

2. Durum Sorgulama

GET /v1/deposit-oturumlari/{referans}
X-Api-Key: fn_...

{
  "referans": "K7P2M9XQ4RTB",
  "durum": "tuketildi",
  "tutar": 1500.0,
  "para_birimi": "TRY",
  "bitis_zamani": "2026-09-12T01:30:00Z",
  "harici_referans": "SIPARIS-9981",
  "talep": { "id": 12, "durum": "onaylandi", "ret_nedeni": "" }
}

durum oturum durumudur: acik, tuketildi (bildirim alındı), suresi_dolmus, iptal. talep alanı, kullanıcı "Ödemeyi Yaptım"a bastıysa dolar; talep durumu beklemede, onaylandi, reddedildi veya iptal olur.

3. Oturum İptali

POST /v1/deposit-oturumlari/{referans}/iptal
X-Api-Key: fn_...

Yalnızca açık oturum iptal edilir. Oturumu açan API anahtarının geri çağırma adresi varsa oturum.iptal olayı kuyruğa alınır (tur: "yatirim", durum: "iptal"). Yanıt: {"referans": "...", "durum": "iptal"}.

4. Çekim Talebi Açma

Kullanıcı para çekmek istediğinde ana site bu ucu çağırır. Talep finans panelindeki Çekim Talepleri kuyruğuna düşer; operatör banka transferini yapıp onaylar veya reddeder.

POST /v1/cekim-talepleri
Content-Type: application/json
X-Api-Key: fn_...

{
  "kullanici_id": "u123",
  "kullanici_adi": "veli123",
  "ad_soyad": "Ahmet Yılmaz",
  "tutar": 2000,
  "banka": "Örnek Banka",
  "hesap_sahibi": "Ahmet Yılmaz",
  "iban": "TR330006100519786457841326",
  "harici_referans": "CEKIM-441",
  "idempotency_key": "wd-u123-441"
}

Tutar paneldeki çekim limitleri arasında, IBAN geçerli olmalıdır. harici_referans ve idempotency_key isteğe bağlıdır (yatırım oturumu ile aynı anlam). Başarılı yanıt (201): {"talep_id": 7, "islem_no": 7, "durum": "beklemede", "tutar": 2000.0, "para_birimi": "TRY", "ret_nedeni": "", "harici_referans": "CEKIM-441"}.

5. Çekim Sorgulama ve İptal

GET /v1/cekim-talepleri/{talep_id}
X-Api-Key: fn_...

POST /v1/cekim-talepleri/{talep_id}/iptal
X-Api-Key: fn_...

Sorgu yanıta güncel durum, varsa ret_nedeni ve harici_referans döner. Yalnızca bekleyen çekim iptal edilir; iptal sonrası ilgili anahtara cekim.iptal (durum iptal) callback'i gönderilir.

Geri Çağırma (Sonuç Bildirimi)

Operatör talebi onaylayınca, reddedince veya bekleyen talep/çekim iptal edilince, yalnızca işlemi oluşturan API anahtarının geri çağırma adresine POST gönderilir (eski kayıtlarda anahtar_id yoksa geriye uyumluluk için tüm etkin anahtarlara yayınlanır).

POST {geri_cagirma_adresi}
Content-Type: application/json
X-Finans-Olay: talep.sonuc
X-Finans-Bildirim-Id: CB-AB12CD34EF
X-Finans-Imza: 9f2c... (gövdenin HMAC-SHA256 imzası, anahtar: imza gizlisi)
X-Finans-Zaman: 2026-09-12T01:35:00Z

{
  "bildirim_id": "CB-AB12CD34EF",
  "olay": "talep.sonuc",
  "referans": "K7P2M9XQ4RTB",
  "talep_id": 12,
  "kullanici_id": "u123",
  "kullanici_adi": "veli123",
  "tutar": 1500.0,
  "para_birimi": "TRY",
  "durum": "onaylandi",
  "ret_nedeni": "",
  "harici_referans": "SIPARIS-9981",
  "zaman": "2026-09-12T01:35:00Z"
}

Olaylar:

talep.sonuc / talep.iptal — yatırım talebi kararı (tur: "yatirim")
cekim.sonuc / cekim.iptal — çekim talebi kararı (tur: "cekim")
oturum.iptal — v1 deposit oturumu iptali, henüz talep yokken (tur: "yatirim", durum: "iptal"; gövdede referans, kullanıcı alanları, harici_referans, tutar)

İmza doğrulama zorunludur: ham gövde + imza gizlisi ile HMAC-SHA256 hesaplayıp X-Finans-Imza ile karşılaştırın. zaman zaten gövdede imzalanır.
Zaman sapması (önerilir): X-Finans-Zaman (veya gövdeki zaman) ile sunucu saati arasındaki fark 5 dakikayı aşıyorsa bildirimi reddedin (replay koruması).
Tekilleştirme: aynı bildirim_id iki kez işlenmemelidir (ağ kesintisinde yeniden gönderilir).
Adresiniz 2xx dönmezse bildirim aralıklarla yeniden denenir. Panel webhook kaydında HTTP durum + kısa gövde özeti tutulur.

Örnek imza doğrulama — ham gövde + imza_gizlisi ile HMAC-SHA256; X-Finans-Imza ile karşılaştırın; X-Finans-Zaman (veya gövdeki zaman) sapması ≤ 5 dakika olmalı.

Python

import hmac, hashlib
from datetime import datetime, timezone

def dogrula(ham_govde: bytes, gelen_imza: str, imza_gizlisi: str,
            zaman_iso: str, max_skew_sn: int = 300) -> bool:
    beklenen = hmac.new(imza_gizlisi.encode(), ham_govde, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(beklenen, gelen_imza):
        return False
    zaman = datetime.fromisoformat(zaman_iso.replace("Z", "+00:00"))
    return abs((datetime.now(timezone.utc) - zaman).total_seconds()) <= max_skew_sn

Node.js

const crypto = require("crypto");

function dogrula(hamGovde, gelenImza, imzaGizlisi, zamanIso, maxSkewSn = 300) {
  const beklenen = crypto.createHmac("sha256", imzaGizlisi)
    .update(hamGovde).digest("hex");
  const a = Buffer.from(beklenen, "utf8");
  const b = Buffer.from(String(gelenImza || ""), "utf8");
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return false;
  const skew = Math.abs(Date.now() - Date.parse(zamanIso)) / 1000;
  return skew <= maxSkewSn;
}
// hamGovde = raw request body (Buffer/string), imza = req.headers["x-finans-imza"]
// zaman = req.headers["x-finans-zaman"] || JSON.parse(hamGovde).zaman

PHP

<?php
function finans_dogrula(string $hamGovde, string $gelenImza, string $imzaGizlisi,
                        string $zamanIso, int $maxSkewSn = 300): bool {
    $beklenen = hash_hmac("sha256", $hamGovde, $imzaGizlisi);
    if (!hash_equals($beklenen, $gelenImza)) {
        return false;
    }
    $zaman = strtotime($zamanIso);
    if ($zaman === false) return false;
    return abs(time() - $zaman) <= $maxSkewSn;
}
// $hamGovde = file_get_contents("php://input");
// $imza = $_SERVER["HTTP_X_FINANS_IMZA"] ?? "";
// $zaman = $_SERVER["HTTP_X_FINANS_ZAMAN"] ?? (json_decode($hamGovde)->zaman ?? "");
?>

Canlı / reverse proxy

Canlıda uygulamayı 127.0.0.1:8080 üzerinde tutup önüne HTTPS terminating reverse proxy (ör. nginx proxy_pass http://127.0.0.1:8080) koyun. Deposit bağlantılarının dış URL’si için ortam değişkeni FINANS_PUBLIC_URL (ör. https://deposit.ornek.com) ayarlayın. Detay: proje README.md → “Canlıda çalıştırma”.

Hata Biçimi

Tüm hatalar tek tip gövdeyle döner:

{ "hata": { "kod": "tutar_aralik_disi", "mesaj": "Tutar 100 ile 500000 arasında olmalıdır." } }

HTTP	Kod	Anlamı
400	`eksik_alan`, `gecersiz_tutar`, `tutar_aralik_disi`, `gecersiz_json`	İstek girdisi hatalı
400	`aktif_hesap_yok`	Panelde etkin hesap yok; finans ekibine bildirin
401	`yetkisiz`	API anahtarı geçersiz veya pasif
403	`adres_engelli`	Sunucu adresi izinli listede değil
404	`oturum_yok`	Referans bulunamadı
409	`oturum_kapali`	Oturum artık açık değil
429	`hiz_siniri`	Çok fazla istek; biraz bekleyip yeniden deneyin

Test Senaryoları

Başarılı yatırım: oturum aç → bağlantıya git → Devam Et → Ödemeyi Yaptım → panelde onayla → geri çağırmanın geldiğini ve imzanın doğrulandığını gör.
Kapsamlı callback: iki API anahtarı ile ayrı callback URL'leri tanımlayın; A anahtarıyla açılan oturumun sonucu yalnızca A'ya gelsin.
Idempotency: aynı idempotency_key ile oturumu iki kez açın; aynı referans dönmeli.
Süre dolumu: panelde oturum süresini 1 dakikaya indir, oturum aç, bekle; bilgi ucunun suresi_dolmus döndüğünü gör.
İptal: açık oturumu iptal et; deposit sayfasının kapandığını ve oturum.iptal callback'inin geldiğini gör. Bekleyen çekimi iptal et; cekim.iptal callback'i gelsin.
Çift bildirim: aynı bildirim_id'yi iki kez karşıla; ikinci işlemin yoksayıldığını gör.
Yanlış imza / eski zaman: imzası bozuk veya |now − zaman| > 5 dk olan çağrıyı reddettiğini gör.

Sürüm Kuralı

/v1 kararlıdır; kırıcı değişiklik yeni sürümle (/v2) gelir. Değişiklikler bu sayfadaki günlüğe işlenir.

Değişiklik günlüğü:

2026-09-12 — oturum.iptal callback, yapılandırılabilir retry/timeout, PHP/Node imza örnekleri, toplu yeniden gönderim.
2026-09-12 — Callback kapsamı (anahtar bazlı), harici_referans, idempotency_key, X-Finans-Zaman, iptal callback'leri, Test Ping.
2026-09-12 — v1 ilk sürüm; çekim uçları ve tur/islem_no alanları eklendi (geriye uyumlu).