API v1

CSP API

Banka dekontu PDF'lerini 7 katmanda, 60'tan fazla adli kontrolle inceleyip orijinal, şüpheli veya sahte kararı veren REST API. JSON konuşan her dille çalışır.

Temel adres{{BASE}}/api/v1
Biçimİstek: multipart/form-data veya application/json · Yanıt: application/json (UTF-8)
Kimlik doğrulamaX-API-Key başlığı (kullanıcıya özel anahtar)
Maksimum dosya15 MB
Ortalama süre0,1 – 1 saniye

Hızlı başlangıç

Size verilen API anahtarını alın. Anahtar yalnızca sunucunuzda kullanılmalı.
Müşterinin yüklediği PDF'i sunucunuzdan /api/v1/analyze adresine gönderin.
Yanıttaki verdict_code'a göre işlem yapın; id'yi siparişinizle birlikte saklayın.
curl -H "X-API-Key: csp_live_xxxxxxxx" \
     -F [email protected] \
     {{BASE}}/api/v1/analyze

Kimlik ve izinler

Her isteğe anahtarınızı ekleyin. Authorization: Bearer csp_live_... biçimi de kabul edilir.

X-API-Key: csp_live_xxxxxxxxxxxxxxxxxxxxxxxx

Anahtarlar kullanıcıya özeldir ve yönetici tarafından şu kısıtlarla üretilir:

KısıtAçıklama
İzinleranalyze dekont analiz etme · read kendi geçmişi ve kota bilgisi · banks banka listesi
Hız sınırıDakikadaki istek sayısı. Aşılınca 429 ve Retry-After döner.
Aylık kotaKullanıcı başına aylık analiz sayısı. Dolunca 429 döner.
IP kısıtıYalnızca izinli IP/CIDR adreslerinden erişim. Diğerleri 403 alır.
Son kullanmaTarihi geçen anahtar 401 alır.
Anahtarı tarayıcıya veya mobil uygulamaya gömmeyin. Kullanıcıdan gelen dosyayı kendi sunucunuza alın, oradan bu API'ye iletin.

Dekont analiz et

POST/api/v1/analyzeizin: analyze

multipart/form-data ile file alanında PDF gönderin.

Base64 ile analiz

POST/api/v1/analyze/base64izin: analyze

Multipart göndermenin zor olduğu ortamlar için. data:application/pdf;base64,... önekli değer de kabul edilir.

{ "file_base64": "JVBERi0xLjcK...", "filename": "dekont.pdf" }

Analizi getir

GET/api/v1/analyses/{id}izin: read

Daha önce yapılmış analizi döndürür. Her kullanıcı yalnızca kendi analizlerini görebilir.

Analiz geçmişi

GET/api/v1/analyses?page=1&size=25&verdict=forgedizin: read
{ "total": 132, "page": 1, "size": 25,
  "items": [ { "id": "ff01d288c2f94cbe", "created_at": "…", "filename": "dekont.pdf", "bank": "Garanti BBVA",
               "sender": "AHMET YILMAZ", "receiver": "MEHMET KAYA", "amount": "9.750,00 TL",
               "risk_score": 100, "verdict_code": "forged", "ref": "GRN2026111800451" } ] }

Hesap ve kota

GET/api/v1/meizin: read
{ "key":   { "name": "Canlı site", "prefix": "csp_live_AbCd12", "scopes": ["analyze","read"], "rate_limit_per_min": 60, "expires_at": null },
  "user":  { "name": "Mağaza A", "company": "A Ltd" },
  "usage": { "this_month": 412, "monthly_quota": 1000, "remaining": 588 } }

Bankalar

GET/api/v1/banksizin: banks
GET/api/v1/healthanahtar gerekmez

Yanıt yapısı

{
  "id": "ff01d288c2f94cbe",
  "created_at": "2026-11-18T14:12:05+00:00",
  "filename": "dekont.pdf",
  "verdict": "SAHTE / DÜZENLENMİŞ",
  "verdict_code": "forged",              // original | suspicious | forged
  "risk_score": 100,                      // 0–100
  "confidence": "yüksek",                 // yüksek | orta | düşük
  "summary": "Mevcut yazı beyaz kutuyla kapatılıp üstüne yeni yazı basılmış…",
  "bank": "Garanti BBVA",
  "fields": {
    "sender": "AHMET YILMAZ",
    "receiver": "MEHMET KAYA",
    "amount": { "value": 9750.0, "currency": "TL", "text": "9.750,00 TL" },
    "amount_in_words": ["1.250,00 TL"],
    "transaction_date": "18.11.2026 14:32",
    "ibans": [{ "iban": "TR33…", "valid": true, "bank": "Akbank" }],
    "ids": [{ "type": "TCKN", "value": "100*****146", "valid": true }],
    "references": ["GRN2026111800451"],
    "description": "Sipariş #4821 ödemesi"
  },
  "findings": [
    { "code": "TEXT_COVERED_REPLACED", "severity": "critical", "weight": 60, "category": "gorsel",
      "message": "Sayfa 1: mevcut yazı beyaz kutuyla kapatılıp üstüne yeni yazı basılmış…" },
    { "code": "AMOUNT_WORDS_MISMATCH", "severity": "critical", "weight": 60, "category": "veri", "message": "…" }
  ],
  "evidence": ["Sayfa yerleşimi Garanti BBVA orijinal şablonuyla örtüşüyor."],
  "categories": { "imza": {"name": "Dijital imza", "score": 0, "count": 0}, "gorsel": {"score": 100, "count": 2}, … },
  "metadata": {…}, "structure": {…}, "signatures": […], "duplicate": {…}
}
verdict_codeVarsayılan eşikÖnerilen işlem
originalrisk < 20İşleme devam edin
suspicious20 – 49Manuel kontrol veya hesap hareketinden teyit
forged≥ 50İşlemi durdurun

Kendi kuralınızı yazacaksanız findings[].code değerlerini kullanın. Bu kodlar sabittir; mesaj metinleri değişebilir.

Bulgu kodları

KodKatmanSeviyeAnlamı

Hata kodları

Hatalarda gövde {"detail": "açıklama"} biçimindedir.

HTTPAnlamı
400Boş dosya veya geçersiz base64
401Anahtar eksik, geçersiz, devre dışı veya süresi dolmuş
403İzin yok, IP izinli değil veya kullanıcı askıda
404Analiz bulunamadı
413Dosya boyut sınırını aşıyor
422Eksik alan (örn. file yok)
429Hız sınırı veya aylık kota doldu (Retry-After başlığına bakın)

Webhook

Hesabınıza webhook adresi tanımlıysa her analizden sonra bu adrese POST gönderilir:

POST https://siteniz.com/dekont-webhook
Content-Type: application/json
X-CSP-Event: analysis.completed
X-CSP-Signature: sha256=5d3c…

{ "event": "analysis.completed", "data": { …analiz yanıtının tamamı… } }

İmzayı, size verilen whsec_… anahtarıyla gövdenin HMAC-SHA256 özetini hesaplayarak doğrulayın:

Telegram uyarıları

Her API anahtarı bir veya birden fazla adlandırılmış Telegram kanalına bağlanır. O anahtarla gelen her dekontun sonucu (gönderen/alıcı adı, tutar, banka, IBAN, referans, risk puanı ve tespit nedenleri) bu kanallara anında gönderilir.

KuralAçıklama
Kanal seviyeleriHer kanal ayrı ayrı sahte, şüpheli, yüksek tutar ve orijinal sonuçlarını alacak şekilde ayarlanır.
BotKanalın kendi botu → API anahtarına özel bot → ana bot. Yönetici kanalları her zaman kendi botunu veya ana botu kullanır.
KapsamTüm dekontlar (yönetici grubu) · bir kullanıcının bütün anahtarları · yalnızca seçilen anahtarlar.

Kendi grubunuzu tanımlatmak için botu grubunuza ekleyip grupta bir mesaj yazmanız yeterli; yönetici paneldeki "Chat bul" ile grubu görüp anahtarınıza bağlar.

SDK'lar

Dil örnekleri

Önerilen akış

Müşteri dekontu sitenize yükler; sunucunuz dosyayı API'ye gönderir.
original ise devam edin, suspicious ise manuel kontrole alın, forged ise işlemi durdurun.
Yüksek tutarlarda karar ne olursa olsun paranın hesaba geçtiğini teyit edin.
Bu servis bir risk değerlendirmesi yapar. Bankanın kendi yazılımıyla hiç iz bırakmadan üretilmiş bir sahte dekont yapısal analizle yakalanamayabilir. Paranın gerçekten gelip gelmediğinin kesin kanıtı hesap hareketidir.