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": "whatsapp" }

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."
}

Alan	Açıklama
`hesaplamaId`	Kayıt UUID’si — daha sonra `GET /hesaplamalar/{id}` ile (girişliyse) tekrar okunabilir
`toplam`	Net tutar (TL) — `maluliyet` ucu istisna: bu alan % orandır, TL değil
`kalemler[]`	`{ ad, tutar, aciklama? }` — hesabın döküm kalemleri
`parametre_versiyonu`	Hesapta kullanılan mevzuat/tarife parametre seti sürümü
`uyari`	Varsa, sonucun ön tahmin niteliğine dair uyarı metni

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ı:

Durum	`kod`	Anlamı
400	`GIRDI_GECERSIZ`	Gövde zod şemasına uymuyor
400	`TELEFON_GECERSIZ`	Telefon `5XXXXXXXXX` biçiminde değil
401	`TOKEN_GECERSIZ`	Girişli uçta token yok/süresi dolmuş
404	`BULUNAMADI`	Kayıt yok (veya başkasına ait)
409	`RAYIC_BEDEL_YOK`	Araç kataloğunda rayiç bedel yok (v1’de manuel giriş yok)
429	`RATE_LIMIT` / `COK_DENEME`	Çok fazla deneme

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.