shopback/cart/API_DOCS.md

Sepet (Cart) API Kullanım Kılavuzu

Bu doküman, alışveriş sepeti (Shopping Cart) API'sinin nasıl kullanılacağını, uç noktaları (endpoints), istek parametrelerini ve örnek senaryoları içerir.

Genel Bilgiler

• Base URL: /api/v1/cart/
• Mantık: Sepet, sunucu tarafında Session (Oturum) tabanlı çalışır.
• Önemli Not: İstemci (Frontend/Mobile), sunucudan dönen sessionid çerezini (cookie) saklamalı ve sonraki tüm isteklerde header içinde geri göndermelidir. Aksi takdirde her istekte yeni, boş bir sepet oluşturulur.

---

Uç Noktalar (Endpoints)

1. Sepeti Görüntüle

Mevcut sepetin içeriğini ve toplam tutarını getirir.

• URL: /api/v1/cart/
• Method: GET

Örnek Yanıt:

{
    "items": [
        {
            "product": {
                "id": 1,
                "title": "Örnek Ürün",
                "price": 100.00,
                "images": "http://localhost:8000/media/...",
                ...
            },
            "quantity": 2,
            "price": "100.00",
            "total_price": "200.00"
        }
    ],
    "total_price": "200.00"
}

---

2. Sepete Ürün Ekle / Güncelle

Sepete yeni bir ürün ekler veya mevcut ürünün miktarını değiştirir.

• URL: /api/v1/cart/add/
• Method: POST

Parametreler (Body - JSON):

Parametre	Tip	Zorunlu	Açıklama
product_id	Integer	Evet	Eklenecek ürünün ID'si.
quantity	Integer	Hayır	Miktar (Varsayılan: 1).
override_quantity	Boolean	Hayır	true ise miktarı direkt eşitler, false ise mevcut miktarın üzerine ekler (Varsayılan: false).

Senaryo A: Sepete Ürün Ekleme (veya Miktar Artırma)

Mevcut miktarın üzerine ekler. (Örn: Sepette 1 tane var, 2 tane daha ekle = 3 olur).

İstek:

{
    "product_id": 1,
    "quantity": 2,
    "override_quantity": false
}

Senaryo B: Miktarı Güncelleme / Azaltma

Miktarı direkt olarak belirtilen sayıya eşitler. (Örn: Sepette 5 tane var, 4'e düşürmek istiyorsunuz).

İstek:

{
    "product_id": 1,
    "quantity": 4,
    "override_quantity": true
}

Senaryo C: Miktarı Sıfırlayarak Silme

Eğer override_quantity: true iken quantity: 0 gönderirseniz, ürün sepetten silinir.

İstek:

{
    "product_id": 1,
    "quantity": 0,
    "override_quantity": true
}

---

3. Sepetten Ürün Silme

Belirli bir ürünü sepetten tamamen kaldırır.

• URL: /api/v1/cart/remove/<product_id>/
• Method: DELETE

Örnek: /api/v1/cart/remove/1/

Yanıt: Güncel sepet içeriğini döndürür (Ekleme işlemiyle aynı formatta).

---

4. Sepeti Temizle

Sepetteki tüm ürünleri siler.

• URL: /api/v1/cart/clear/
• Method: POST

Yanıt:

{
    "message": "Cart cleared"
}

---

Frontend Entegrasyonu İçin İpuçları (React/Vue/Mobile)

1. Cookie Yönetimi: Axios veya Fetch kullanırken credentials: 'include' veya withCredentials: true ayarının açık olduğundan emin olun. Bu, Django'nun session cookie'sini tarayıcının saklamasını ve göndermesini sağlar.

   // Axios Örneği
   axios.post('/api/v1/cart/add/', data, {
       withCredentials: true
   });
   

2. Ürün Detayları: Sepet yanıtı (items dizisi) içindeki product objesi, ProductSerializer'dan gelen tüm veriyi (resim, slug, başlık vb.) içerir. Ekstra bir istek atmanıza gerek yoktur.

3. Toplam Fiyat: Sepet toplamı total_price alanında string decimal olarak gelir (Örn: "1250.50"). Frontend'de gösterirken formatlamanız gerekebilir.