Etsy API Entegrasyonu: Türk El Yapımı Satıcıları İçin Teknik Rehber

Etsy API Neden Kullanılır?

Etsy'nin yönetim paneli küçük hacimler için yeterlidir; ancak ürün sayısı ve sipariş akışı büyüdükçe API entegrasyonu zorunlu hale gelir.

• Ürün listeleme ve varyant yönetimini toplu yapma
• Sipariş bildirimlerini kendi sisteminize almak
• Stok seviyelerini WooCommerce / ERP ile senkronize etmek
• Mağaza istatistiklerini kendi raporlama aracınıza taşımak
• Fiyat güncellemelerini döviz kuruna göre otomatize etmek (USD bazlı)

Etsy API v3 Mimarisi

Etsy 2023 itibarıyla eski v2 API'yi emekliye aldı. Tüm yeni entegrasyonlar Etsy Open API v3 (REST, JSON) üzerinden yapılmalıdır.

• Listing API — ürün oluşturma, güncelleme, fotoğraf yükleme, varyant yönetimi
• Receipt API — sipariş okuma, durum güncelleme, kargo takibi
• Shop API — mağaza bilgisi, istatistik ve favori listesi
• Taxonomy API — ürün kategorisi ve özellik değerleri
• Rate limit: dakikada 10 istek (Basic), dakikada 100 istek (Advanced — başvuru gerekir)

OAuth 2.0 Kurulumu

Etsy API erişimi için Etsy Developer hesabı açıp uygulama oluşturmanız gerekir. Onay süreci genellikle 1–3 iş günü içinde tamamlanır.

• 1. etsy.com/developers → 'Create a New App' ile uygulama oluşturun
• 2. Keystring (API Key) ve Shared Secret alın
• 3. PKCE destekli Authorization Code Flow ile kullanıcı token'ı üretin
• 4. Access Token (1 saat) + Refresh Token süresiz → yenileme mekanizması zorunlu
• 5. Scopes: listings_r, listings_w, transactions_r, shops_r seçin
• 6. Redirect URI'yi uygulamanıza kaydedin (localhost test için geçerli)

Türk Satıcıların Dikkat Etmesi Gerekenler

Etsy Türkiye'de doğrudan banka hesabına ödeme yapmamaktadır. Bu durum Türk satıcılar için ek adımlar gerektirir.

• Ödeme alımı: Payoneer veya Wise USD hesabı açılmalı — kurulum 3–5 iş günü
• KDV: Etsy, AB müşterilerine otomatik KDV ekler; Türkiye'de ek yükümlülük yok
• Kargo: Etsy'nin yerleşik kargo hesabı Türkiye'yi desteklemez — PTT veya Yurtiçi entegrasyonu ayrıca yapılmalı
• Döviz kuru: Ürün fiyatları USD girilmeli; TL maliyet hesabı için otomatik kur güncellemesi scripti önerilir
• Satış kotası: Yeni Etsy mağazaları ilk 3 ayda 250 liste limiti ile başlar

Entegrasyon Adımları ve Süre

Solman Digital tarafından gerçekleştirilen Etsy API projelerinde standart zaman çizelgesi şu şekildedir:

• Gün 1–2: OAuth kurulumu, API bağlantı testi, mağaza veri doğrulama
• Gün 3–5: Listing API — toplu ürün okuma / güncelleme / fotoğraf yükleme
• Gün 6–8: Receipt API — sipariş webhook, kargo takibi, durum güncelleme
• Gün 9–10: Stok senkronizasyonu (WooCommerce / ERP bağlantısı)
• Gün 11–12: Test, hata yönetimi, monitoring kurulumu
• Toplam: 200 SKU'ya kadar mağazalar için 10–12 iş günü

Sık Sorulan Sorular