Hızlı Başlangıç

Bu rehber, KazaRehberi API'sine ilk isteğinizi göndermenizi sağlar.

Base URL: https://api.kazarehberi.com.tr — tüm iş uçları /v1 öneki altındadır (ör. https://api.kazarehberi.com.tr/v1/hesaplamalar/deger-kaybi). Yalnızca /health sürümsüzdür.

Public mı, girişli mi?

Hesaplama uçlarının çoğu public'tir — token GEREKMEZ. Authorization: Bearer başlığı gönderirseniz (ve geçerliyse) hesaplama otomatik olarak o kullanıcıya bağlanır; göndermezseniz hesaplama anonim (misafir) olarak kaydedilir ve daha sonra /hesaplamalar/sahiplen ile bir telefon numarasına bağlanabilir.

GET /hesaplamalar (geçmiş listesi) ve GET /hesaplamalar/{id} (detay) ise zorunlu girişlidir — geçerli bir Authorization: Bearer <accessToken> olmadan 401 TOKEN_GECERSIZ döner.

Adım 1 — Kimlik doğrulama (opsiyonel, OTP tabanlı)

KazaRehberi'nde parola yoktur; oturum telefon numarasına gönderilen tek kullanımlık kodla (OTP) açılır. Mobil/sunucu tarafı entegrasyonlarda iki adım vardır.

1a. Kod iste

curl -X POST https://api.kazarehberi.com.tr/v1/auth/otp-iste \
  -H "Content-Type: application/json" \
  -d '{"telefon": "5XXXXXXXXX", "turnstileToken": "<cloudflare-turnstile-token>"}'

Yanıt:

{ "gonderildi": true, "tekrarSaniye": 60, "kanal": "sms" }

turnstileToken web istemcileri için zorunludur (Cloudflare Turnstile bot koruması). Mobil uygulama, X-App-Key başlığıyla kimliğini kanıtlayarak bu adımdan muaf tutulabilir.

1b. Kodu doğrula → token al

curl -X POST https://api.kazarehberi.com.tr/v1/auth/otp-dogrula \
  -H "Content-Type: application/json" \
  -d '{"telefon": "5XXXXXXXXX", "kod": "123456", "platform": "mobil"}'

platform: "mobil" gönderildiğinde token'lar gövdede döner:

{
  "yeniKullanici": false,
  "profilTamamMi": true,
  "kullanici": { "id": "…", "adSoyad": "…", "rol": "musteri" },
  "accessToken": "eyJhbGciOi...",
  "refreshToken": "…"
}

platform: "web" gönderildiğinde token'lar HttpOnly cookie'ye yazılır, gövdede token bulunmaz — web istemcileri credentials: 'include' ile isteğe devam eder.

Access token süresi dolduğunda POST /auth/yenile ile (cookie veya {"refreshToken": "…"} gövdesiyle) yenilenir.

Adım 2 — Bir hesaplama isteği at

Örnek: geçici iş göremezlik (kazanç kaybı) hesaplaması — public, token gerekmez.

curl -X POST https://api.kazarehberi.com.tr/v1/hesaplamalar/kazanc-kaybi \
  -H "Content-Type: application/json" \
  -d '{
    "kazaTarihi": "2026-05-01",
    "isGoremezlikSuresiGun": 30,
    "aylikNetGelir": 20000,
    "kusurOrani": 20
  }'

Eşdeğer JavaScript fetch:

const yanit = await fetch('https://api.kazarehberi.com.tr/v1/hesaplamalar/kazanc-kaybi', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    kazaTarihi: '2026-05-01',
    isGoremezlikSuresiGun: 30,
    aylikNetGelir: 20000,
    kusurOrani: 20,
  }),
});
const veri = await yanit.json();

Girişli bir kullanıcı adına kaydetmek isterseniz Authorization: Bearer <accessToken> başlığını ekleyin — girdi şeması ve yanıt aynı kalır, yalnızca hesaplama o kullanıcıya bağlanır:

curl -X POST https://api.kazarehberi.com.tr/v1/hesaplamalar/kazanc-kaybi \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -d '{ "kazaTarihi": "2026-05-01", "isGoremezlikSuresiGun": 30, "aylikNetGelir": 20000, "kusurOrani": 20 }'

Adım 3 — Yanıtı oku

Tüm hesaplama uçları aynı temel şekli döner:

{
  "hesaplamaId": "b3f1c9e0-....-....-....-............",
  "toplam": 16000,
  "kalemler": [
    { "ad": "Brüt kazanç kaybı", "tutar": 20000 },
    { "ad": "Kusur indirimi (%20)", "tutar": -4000 }
  ],
  "parametre_versiyonu": 3,
  "uyari": "Kesin süre kurul raporuyla belirlenir; bu bir ön hesaplamadır."
}

Hata durumunda

Hatalar HER ZAMAN aynı şekli döner:

{ "hata": { "kod": "GIRDI_GECERSIZ", "mesaj": "İstek gövdesi doğrulanamadı" } }

Sık görülen hata kodları:

fetch ile hata kontrolü:

if (!yanit.ok) {
  const { hata } = await yanit.json();
  console.error(hata.kod, hata.mesaj);
}

Sonraki adım: Örnek Senaryolar ile uçtan uca vaka çalışmalarını inceleyin.