Koza E-Ticaret Zekâ Platformu – Entegrasyon Gereksinimleri

1) Amaç

Koza E-Ticaret Zekâ Platformu; e-ticaret ve pazaryeri verilerini analiz ederek ürün/kategori/kanal bazlı
gerçek kârlılığı görünür kılar. Komisyon, kargo, iade ve reklam harcamalarının kârı nasıl etkilediğini
ortaya çıkarır; “çok satan ama zarar ettiren” alanları ayıklar ve yönetime aksiyon önceliği sunar.

Bu doküman, platformun sağlıklı çalışması için gerekli veri alanlarını, entegrasyon yöntemlerini ve teknik ön koşulları tanımlar.

2) Kapsam

• Analiz kapsamı: Sipariş, iade/iptal, komisyon/kesinti, kargo/lojistik, reklam (opsiyonel: maliyet, stok, teslimat SLA)
• Veri kullanım amacı: Kârlılık analizi, zarar noktası uyarıları, iade riski, reklamın kâra etkisi, yönetici özeti
• Çalışma prensibi: Koza platformu sistemlere yazmaz; süreçlere müdahale etmez, sadece okur.

3) Veri Kaynakları

Koza E-Ticaret Zekâ Platformu aşağıdaki kaynaklardan veri bekler (en az 1 satış kanalı ile başlanabilir):

• E-ticaret altyapısı (sipariş, ürün, müşteri, stok) – örn. Shopify/WooCommerce/özel altyapı
• Pazaryerleri (sipariş, komisyon/kesinti, iade, kampanya) – örn. Trendyol/Hepsiburada/Amazon vb.
• Reklam platformları (harcama, kampanya, dönüşüm sinyalleri) – örn. Meta/Google/Marketplace Ads
• Kargo / lojistik (gönderi, ücret, teslimat süreleri, iade kargo) – kargo firması veya lojistik yazılımı
• (Opsiyonel) ERP / muhasebe (ürün maliyeti/cost, operasyon maliyet parametreleri)

4) Zorunlu Veri Setleri

Aşağıdaki veri setleri sağlanmadan Koza E-Ticaret Zekâ Platformu’nun kârlılık, iade ve zarar noktası analizleri
sağlıklı çalışmaz.

5) Opsiyonel Veri Setleri

Aşağıdaki veri setleri zorunlu değildir; ancak kârlılık doğruluğu, stok/teslimat etkisi ve gelişmiş optimizasyon
senaryoları için yüksek değer sağlar.

6) Entegrasyon Yöntemi

Koza E-Ticaret Zekâ Platformu sistemlere yazmaz; sadece okur. Entegrasyon read-only çalışır ve sistem üzerinde veri değişikliği yapılmaz.

• REST API: JSON tabanlı uç noktalar üzerinden veri okuma (önerilir)
• Webhook (ops.): Yeni sipariş/iade olaylarını hızlı yakalamak için
• Database View: Sadece okuma yetkili view’ler (özel altyapılar için)
• Scheduled Export: JSON/CSV dışa aktarım (geçici / başlangıç yöntemi)

7) Performans & Format Beklentileri

• Veri güncelliği: Sipariş/İade 5–15 dk, komisyon/kesinti günlük, reklam günlük (ops. saatlik)
• Zaman damgası: OrderDate, ReturnDate, (varsa) ShipDate/DeliveredDate önerilir
• Tarih-saat formatı: ISO 8601 (timezone dahil)
• Karakter seti: UTF-8
• Referans bütünlüğü: OrderId–OrderItemId, SKU eşleşmeleri tutarlı olmalıdır
• Tekilleştirme: Aynı kayıt tekrar geliyorsa idempotent upsert yapılabilmelidir
• Incremental sync: updatedAt / lastModified alanı varsa tercih edilir

8) Hazırlık Kontrol Listesi

Aşağıdaki maddelerin tamamı “Evet” ise, Koza E-Ticaret Zekâ Platformu kısa sürede devreye alınabilir.

• Sipariş başlığı (Orders) ve sipariş kalemleri (OrderItems) tutuluyor
• İade/iptal/değişim kayıtları (Returns) erişilebilir
• Kanal/pazaryeri komisyon ve kesintileri alınabiliyor
• Kargo/gönderi verileri (shipments) alınabiliyor (opsiyonel ama önerilir)
• Reklam harcaması kampanya bazında erişilebilir
• Read-only API/WebService/DB View veya export erişimi sağlanabilir
• SKU standardı tutarlı (pazaryeri SKU ↔ mağaza SKU eşleşebilir)
• (Opsiyonel) Ürün maliyeti (cost) sağlanabilir

9) Örnek API Endpoint’leri

Aşağıdaki uç noktalar örnek amaçlıdır. Altyapı/pazaryeri mimarisine göre isimler değişebilir.

/api/orders
/api/order-items
/api/returns
/api/fees-commissions
/api/shipments
/api/adspend
/api/products
/api/product-costs
/api/stock-levels

Yetkilendirme önerisi: OAuth2 / API Key + SSL/TLS + (ops.) IP Whitelist