Kolay Deniz Market API

Sözleşme kuralları

Kolay Deniz Market backend'inin dış paylaşıma açık REST arayüzü.

Anlatımlı referans, davranış notları ve entegrasyon kontrol listesi için API.md dosyasına bakın. Bu spec ile o doküman çeliştiğinde, çalışan sistemin davranışı esastır.

Sözleşme kuralları:

• Tüm parasal alanlar tam sayı kuruştur (12550 = 125,50 ₺). Ürün fiyatları KDV dahil satış fiyatıdır.
• Anlık zamanlar ISO-8601 UTC string'dir. Takvim tarihleri (YYYY-MM-DD) ve slot dakikaları Europe/Istanbul yereldir.
• 2xx olmayan her yanıt ApiError zarfını kullanır; istemci mantığı error koduna bakmalıdır, HTTP statüsüne veya message metnine değil.
• Yanıtlara haber verilmeden yeni alan eklenebilir; bilinmeyen alanlar yok sayılmalıdır.

Kimlik doğrulama

Authorization: Bearer <accessToken>. Access token'ın varsayılan ömrü 15 dakikadır; POST /auth/refresh ile yenilenir.

Her uç, referansta hangi kimliği istediğini rozetinde yazar: Bearer personel/müşteri token'ı, x-api-key satıcı makine anahtarı, Herkese açık kimlik istemez. Giriş akışının kendisi Auth bölümündedir.

Satıcı makine anahtarı

Satıcı makine anahtarı — x-api-key: kdm_<ortam>_<önek>_<gizli>.

Tek parçadır: ayrı "API key + secret key" çifti yoktur, anahtarın tamamı tek başlıkta gider. <ortam> üretimde live, diğer her yerde test; böylece test anahtarının üretime yapıştırılması sessizce yetkisiz kalmak yerine görünür biçimde yanlış olur.

Anahtar yalnızca üretildiği anda bir kez gösterilir; sunucuda argon2 ile hash'lenip saklandığı için sonradan kurtarılamaz, kaybolursa yenisi kesilir. Yetkiler anahtara bağlı kapsamlarla (scope) sınırlıdır.

Hata modeli

2xx olmayan her yanıt aynı zarfı kullanır:

• error — makine tarafından okunacak, sabit kod. İstemci mantığı bu alana bakmalıdır, HTTP statüsüne veya message'a değil.
• message — insan okur; opsiyonel, metni haber verilmeden değişebilir.
• details — yalnızca doğrulama hatalarında; alan bazlı sorunlar.
• Bazı hatalar ek bağlam taşır (ör. slot_range_too_wide → maxDays, category_has_products → products, unique_constraint_violation → fields).

{
  "error": "validation_failed",
  "message": "…",
  "details": { "fieldErrors": { "priceKurus": ["Expected number, received string"] } }
}

Hata kodu kataloğu

Hız sınırları

Sayfalama

Liste uçları aynı zarfı döner:

Query parametreleri: page (≥1, varsayılan 1), perPage (1–100, varsayılan 24). search parametreleri en fazla 64 karakterdir ve %, _, \ karakterleri sunucuda temizlenir.

{ "items": [ … ], "page": 1, "perPage": 24, "total": 137, "totalPages": 6 }

Uç nokta referansı