Entegratör API — Genel Bakış

Bu bölüm tema geliştiricileri için değil, bir mağazanın verisini dışarıdan okuyup yazmak isteyenler içindir: ERP/muhasebe senkronizasyonu, pazaryeri (Trendyol, Hepsiburada vb.) sipariş aktarımı, özel bir stok yönetim aracı gibi. Winkwop tarafında buna "entegrasyon uygulaması" denir.

Zihinsel model

Mağaza sahibi panelde Uygulamalar ekranından kendi uygulamasını oluşturur (bkz. /admin/apps → "Uygulama oluştur"). Bu işlem:

1. Bir uygulama kaydı açar (yalnızca o mağazaya görünür),
2. Seçtiği izinlerle (scopes) bir API anahtarı üretir,
3. Anahtarı bir kez gösterir — ham hâli bir daha hiçbir yanıtta dönmez.

Siz (entegratör) bu anahtarı alıp kendi sisteminizde saklarsınız ve her istekte X-Api-Key başlığıyla gönderirsiniz. JWT/oturum yok — anahtar başlı başına kimlik doğrulamadır ve süresi yoktur (elle "yeniden oluştur" denene kadar geçerlidir).

Mağaza paneli                  Sizin sisteminiz              Winkwop API
──────────────                 ─────────────────              ───────────
Uygulama oluştur, izin seç
Anahtarı kopyala      ──────►  X-Api-Key: wk_sk_...    ──────►  /api/v1/integration/...
                                                                 (yalnızca izinli uçlar)

Taban adres

https://api.winkwop.com/api/v1/integration

Tüm entegrasyon uçları bu önekin altındadır — panelin kendi kullandığı /api/v1/products gibi uçlarla karıştırmayın, onlar JWT/oturum ister, API anahtarıyla çalışmaz.

Kimlik doğrulama

Her istekte:

curl https://api.winkwop.com/api/v1/integration/products \
  -H "X-Api-Key: wk_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Başlık eksik, boş veya geçersizse 401 Unauthorized döner (gövdesiz). Mağaza aktif değilse (askıya alınmış vb.) 403 Forbidden döner.

İzinler (scopes)

Bir anahtar yalnızca kendisine verilen izinlerin kapsadığı uçlara erişebilir. İzin dışı bir uca istek atarsanız 403 Forbidden alırsınız (gövdesiz — bu, uygulama hatalarından farklı olarak middleware seviyesinde kesilir).

İzin	Neyi açar
read_products	Ürün listesi/detayı okuma
write_products	Ürün oluşturma, güncelleme, silme, CSV/XML içe aktarma
read_orders	Sipariş listesi/detayı okuma
write_orders	Sipariş oluşturma, durum/kargo takip güncelleme
read_categories	Kategori listesi/detayı okuma
write_categories	Kategori oluşturma, güncelleme, silme
read_inventory	Ürün başına depo bazlı stok okuma
write_inventory	Stok seviyesi güncelleme
read_discounts	Kampanya ve kupon listesi/detayı okuma
write_discounts	Kampanya ve kupon oluşturma, güncelleme, silme
read_customers	Müşteri listesi/detayı okuma
write_customers	Müşteri oluşturma, güncelleme, silme

Bir uygulamanın izinlerini sonradan değiştirmek isterseniz — panelde uygulama detay sayfasındaki Düzenle butonuyla açılır/kapatılır. Anahtar aynı kalır, değişiklik bir sonraki istekte hemen geçerli olur; yeniden anahtar üretmenize gerek yoktur.

Hata biçimi

Uygulama seviyesindeki hatalar (izin yeterli ama istek geçersiz, kayıt yok vb.) tutarlı bir JSON gövdesiyle döner:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Ürün bulunamadı"
  }
}

HTTP	code	Anlamı
400	BAD_REQUEST	Gövde eksik/geçersiz alan
401	UNAUTHORIZED	Anahtar eksik/geçersiz (gövdesiz — middleware seviyesi)
403	FORBIDDEN	İzin yetersiz (gövdesiz) veya mağaza aktif değil
404	NOT_FOUND	Kayıt bulunamadı ya da başka mağazaya ait
409	CONFLICT	Çakışan kayıt (ör. aynı SKU)
422	VALIDATION_ERROR	Alan bazlı doğrulama hatası
500	INTERNAL_ERROR	Beklenmeyen hata

404, kaydın hiç var olmadığı durumla başka bir mağazaya ait olduğu durumu ayırt etmez — anahtarınız yalnızca kendi mağazanızın verisini görebilir, başka bir tenant_id'ye ait bir ID denemeniz de 404 döner.

Sırada ne var

• Ürünler — listeleme, SKU ile upsert, varyantlar, satış kanalları, CSV/XML içe aktarma
• Stok — depo bazlı stok okuma/güncelleme
• Depolar — stok konumlarını keşfetme
• Siparişler — çekme, durum/kargo güncelleme
• Kategoriler
• Müşteriler
• Kampanya ve kuponlar

Senkronizasyon yapıyorsanız

Bir ERP, pazaryeri ya da muhasebe sisteminden düzenli ürün/stok senkronizasyonu kuruyorsanız Ürünler sayfasındaki SKU ile upsert ve varyant eşleştirme bölümlerini mutlaka okuyun — sıradan POST/PUT akışından farklı olarak bu uçlar tekrarlanan çağrılarda güvenlidir (yinelenen ürün/varyant açmaz).