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ğrulama | X-API-Key başlığı (kullanıcıya özel anahtar) |
| Maksimum dosya | 15 MB |
| Ortalama süre | 0,1 – 1 saniye |
Hızlı başlangıç
/api/v1/analyze adresine gönderin.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ıt | Açıklama |
|---|---|
| İzinler | analyze 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 kota | Kullanı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 kullanma | Tarihi geçen anahtar 401 alır. |
Dekont analiz et
/api/v1/analyzeizin: analyzemultipart/form-data ile file alanında PDF gönderin.
Base64 ile analiz
/api/v1/analyze/base64izin: analyzeMultipart 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
/api/v1/analyses/{id}izin: readDaha önce yapılmış analizi döndürür. Her kullanıcı yalnızca kendi analizlerini görebilir.
Analiz geçmişi
/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
/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
/api/v1/banksizin: banks/api/v1/healthanahtar gerekmezYanı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_code | Varsayılan eşik | Önerilen işlem |
|---|---|---|
| original | risk < 20 | İşleme devam edin |
| suspicious | 20 – 49 | Manuel 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ı
| Kod | Katman | Seviye | Anlamı |
|---|
Hata kodları
Hatalarda gövde {"detail": "açıklama"} biçimindedir.
| HTTP | Anlamı |
|---|---|
| 400 | Boş dosya veya geçersiz base64 |
| 401 | Anahtar eksik, geçersiz, devre dışı veya süresi dolmuş |
| 403 | İzin yok, IP izinli değil veya kullanıcı askıda |
| 404 | Analiz bulunamadı |
| 413 | Dosya boyut sınırını aşıyor |
| 422 | Eksik alan (örn. file yok) |
| 429 | Hı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.
| Kural | Açıklama |
|---|---|
| Kanal seviyeleri | Her kanal ayrı ayrı sahte, şüpheli, yüksek tutar ve orijinal sonuçlarını alacak şekilde ayarlanır. |
| Bot | Kanalın kendi botu → API anahtarına özel bot → ana bot. Yönetici kanalları her zaman kendi botunu veya ana botu kullanır. |
| Kapsam | Tü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ış
original ise devam edin, suspicious ise manuel kontrole alın, forged ise işlemi durdurun.