# E-ticaret entegrasyonu

> Sayfalı JSON ürün API'si, changedSince ile değişiklik takibi, canlı fiyat/stok doğrulama, anahtar bazlı kota, fiyat kuralları ve görsel senkronu.

Kendi web sitenizi, ERP'nizi veya pazaryeri aracınızı Giyimport ürün havuzuna bağlayın. API anahtarınızla ürünleri sayfalı JSON olarak alır, yalnızca değişenleri çeker ve sepete eklemeden önce canlı fiyat/stok doğrularsınız.

## API anahtarları ve istek limitleri

### Anahtar yönetimi

- Ne yapar: Panelden API anahtarı oluşturur, yeniler (rotasyon) ve iptal edersiniz.
- Nasıl çalışır: Anahtar yalnızca oluşturulduğu anda bir kez gösterilir; sistemde SHA-256 özeti saklanır.
- Çözdüğü problem: Sızan bir anahtarın fark edilmeden kullanılmaya devam etmesi.
- Teknik detay: Başlık: x-api-key: gyi_… veya Authorization: Bearer gyi_… · Paket başına aktif anahtar sınırı.

### Kota

- Ne yapar: Her paket 30 günlük bir istek kotasıyla gelir; kota aşıldığında API 429 döner.
- Nasıl çalışır: Hesabınızdaki tüm anahtarların istekleri birlikte sayılır; kullanım panelde 24 saat / 7 gün / 30 gün kırılımıyla görünür.
- Çözdüğü problem: Beklenmedik maliyet ve kontrolsüz tüketim.
- Teknik detay: Yanıt kodları: 401 geçersiz anahtar · 403 paket gerekli · 429 kota aşıldı.

## Uç noktalar

| Metot ve yol | Ne döner |
| --- | --- |
| GET /api/v1/products | Sayfalı ürün listesi (page, limit ≤ 100, q, category, supplier, changedSince) |
| GET /api/v1/products/{id} | Tek ürün: varyantlar, görseller, özellikler, fiyatlar |
| GET /api/v1/products/{id}/live | Kaynak siteden anlık fiyat ve stok doğrulaması |
| GET /api/v1/product-groups | Aynı modelin renklerini gruplayan liste |
| GET /api/v1/suppliers | Kaynaklar ve aktif ürün sayıları |
| GET /api/v1/feed.xml | Kapsamdaki tüm aktif ürünler (XML) |

## Webhook yerine değişiklik takibi (polling)

### changedSince

- Ne yapar: Son çekiminizden bu yana değişen ürünleri döner.
- Nasıl çalışır: Son başarılı çekim zamanınızı saklayıp sonraki istekte changedSince parametresiyle gönderirsiniz.
- Çözdüğü problem: Her seferinde tüm kataloğu çekmenin maliyeti.
- Teknik detay: Ürün veya kaynak kaydının güncellenme zamanına göre filtrelenir; ISO 8601 tarih kabul eder.

### Canlı doğrulama

- Ne yapar: Müşteriniz sepete eklerken ürünün kaynak sitedeki güncel fiyat ve stoğunu doğrular.
- Nasıl çalışır: /live uç noktası kaynak sayfayı anlık okur; fiyat değiştiyse fiyat geçmişine yazar ve havuzu günceller.
- Çözdüğü problem: Tedarikçide fiyatı değişmiş ya da bitmiş ürünün satılması.
- Teknik detay: Yanıt: price, suggestedPrice, stock, inStock, active, variants[], checkedAt.

## Kategori, özellik ve fiyat kuralları

### Kategori ve özellik verisi

- Ne yapar: Her ürün kategori, tam kategori yolu ve özellik listesiyle gelir; deneme ve ürün sınırlı paketlerde kapsam kategori seçimine göre oluşur.
- Nasıl çalışır: Kaynak sitedeki kategori ağacı ve özellikler taramada saklanır, API ve XML'de aynı adlarla döner.
- Çözdüğü problem: Kendi kategori ağacınıza eşleme için ham veriye ulaşamamak.
- Teknik detay: Alanlar: category, categoryPath, attributes[{name, value}].

### Fiyat kuralları

- Ne yapar: Satış fiyatı, maliyet üzerine kâr marjı, kargo ücreti ve sabit tutar eklenerek hesaplanır; yuvarlama kuralı uygulanır.
- Nasıl çalışır: Kurallar kaynak bazında tanımlanır; API ve XML'deki salePrice/suggestedPrice alanı bu kurallarla gelir. Pazaryeri fiyat gönderiminde mağaza bazında ek yüzde ve sabit tutar uygulanabilir.
- Çözdüğü problem: Her üründe fiyatı elle hesaplamak.
- Teknik detay: Yuvarlama seçenekleri: kuruş hassasiyeti, ,90 ile biten, 100'e yuvarlanıp ,99 ile biten.

### Görsel senkronizasyonu

- Ne yapar: Ürün görselleri kaynak siteden indirilip Giyimport sunucusunda barındırılır.
- Nasıl çalışır: Görsel senkronu eksik görselleri arka planda indirir; API ve XML'deki görsel adresleri kendi alan adımızdan döner.
- Çözdüğü problem: Kaynak sitenin görsel adreslerini değiştirmesiyle kırılan ürün görselleri.
- Teknik detay: Sıralı görsel listesi; varyanta özel görseller variant.imageUrl alanında.

## Örnek istek

```bash
curl -H "x-api-key: gyi_…" \
  "https://api.giyimport.com/api/v1/products?limit=100&page=1&changedSince=2026-11-01T00:00:00Z"
```