Etsy Open API v3 ve OAuth 2.0: Etsy mağazanızı bağlarken bilmeniz gerekenler
Etsy, satıcı araçlarının mağazaya erişimini Open API v3 ile ve OAuth 2.0 yetkilendirmesiyle sağlar. Pazaryerlerinin çoğunda alıştığınız "panelden anahtar al, yazılıma yapıştır" akışı Etsy'de yoktur; bunun yerine bir onay ekranı vardır. Bu fark satıcıları bazen şaşırtır. Bu yazı, Etsy'nin resmi geliştirici dokümanına dayanarak akışı satıcı gözüyle anlatır.
Open API v3 nedir?
Etsy'nin güncel API'si Open API v3'tür; önceki sürüm (v2) kullanımdan kaldırılmıştır. v3, mağaza, ürün (listing), stok, sipariş (receipt) ve kargo işlemlerini kapsar. Üçüncü taraf bir yazılımın (entegrasyon paneli) Etsy'ye erişmesi için Etsy'de kayıtlı bir uygulama olması ve bu uygulamanın sizin mağazanız için yetkilendirilmesi gerekir. Yetkilendirmeyi siz, Etsy'nin onay ekranında yaparsınız.
Satıcı için anlamı: entegrasyon sağlayıcınızın Etsy tarafında onaylı bir uygulaması olmalıdır; bağlantı sırasında "bu uygulamanın mağazanıza erişmesine izin ver" ekranı görmeniz normaldir.
OAuth 2.0 akışı: onay, jeton, yenileme
Etsy'nin kimlik doğrulama dokümanı akışı şöyle tanımlar: uygulama sizi Etsy'nin onay sayfasına yönlendirir; hangi yetkileri (kapsamları) istediğini listeler; siz onaylarsınız; Etsy uygulamaya kısa ömürlü bir erişim jetonu ve onu yenilemek için bir yenileme jetonu verir. Akış PKCE adı verilen ek bir güvenlik katmanıyla korunur; bunun satıcıya görünen bir tarafı yoktur.
- Erişim jetonu kısa ömürlüdür; dokümanda belirtilen süre dolduğunda uygulama yenileme jetonuyla yenisini alır.
- Yenileme jetonunun da bir ömrü vardır; uygulama uzun süre kullanılmazsa yeniden onay gerekebilir.
- İzni istediğiniz an Etsy hesap ayarlarından iptal edebilirsiniz; o anda entegrasyon durur.
OAuth kavramını daha geniş anlatım için API nedir yazısına bakın.
Kapsamlar (scope): yazılım neye erişebilir?
Onay ekranında uygulamanın istediği yetkiler listelenir: ürünleri okuma/yazma, siparişleri okuma, mağaza bilgilerini okuma gibi. Stok senkronu için ürün yazma yetkisi, sipariş listesi için sipariş okuma yetkisi gerekir. Onayladığınız kapsamlar dışında işlem yapılamaz; bu, API anahtarına göre daha ince bir denetim sağlar. Yazılım sonradan yeni bir kapsam isterse yeniden onay ekranı görürsünüz.
Stok ve ürün: Etsy'nin ürün modeli
Etsy'de ürün "listing"dir ve varyasyonlar (renk, boyut) listing içinde tanımlanır; stok, varyasyon kombinasyonu bazında tutulabilir. Her varyasyona SKU verilebilir ve pazaryeri entegrasyonu bu SKU üzerinden eşleştirme yapar. SKU'suz listing'ler eşleştirmede elle onay gerektirir; bu yüzden Etsy ürünlerinize diğer kanallarla aynı SKU'yu vermek senkronu kolaylaştırır (barkod ve SKU rehberi).
Etsy'de ürünün aktif/pasif durumu da API üzerinden okunur; stok sıfıra düştüğünde listing otomatik olarak satıştan kalkabilir ve stok gelince yeniden aktifleştirilmesi gerekebilir. Entegrasyon panelinin bu durumu yönetip yönetmediğini kontrol edin.
Siparişler, kargo ve döviz
Etsy siparişleri "receipt" olarak gelir; entegrasyon bunları pazaryeri siparişleriyle aynı listeye koyar. Yurt dışı siparişlerde kargo takip numarası ve taşıyıcı bilgisi API üzerinden Etsy'ye yazılır; alıcı bildirimi böylece otomatik gider. Tutarlar mağaza para biriminde gelir; kâr/zarar hesabında kur dönüşümü ve Etsy'nin ücretleri (listeleme, işlem, ödeme işleme) dikkate alınmalıdır. Kâr/zarar hesabı rehberi kanal bazlı hesap için genel çerçeveyi verir.
Bağlantı sorunları ve çözümleri
- "Yetki süresi doldu": yenileme jetonu geçersiz; bağlantıyı yeniden onaylayın.
- "İzin yok": istenen kapsam onaylanmamış; bağlantıyı kaldırıp tüm kapsamlarla yeniden onaylayın.
- Stok yazılmıyor: listing pasif veya SKU eşleşmesi yok; platform kapsamı raporuna bakın.
- İstek sınırı: Etsy günlük ve saniyelik istek sınırları uygular; toplu güncellemeler dakikalar alabilir.
Etsy mağazanızı Saystok'a bağlama adımları bu rehberde; ücretsiz deneyerek başlayabilirsiniz.
Etsy'nin diğer pazaryerlerinden farkı: uluslararası operasyon
Etsy çoğu Türk satıcı için ilk yurt dışı kanaldır ve entegrasyon dışında da operasyonel farklar getirir. Siparişler farklı ülkelere gider; kargo seçenekleri, teslimat süreleri ve gümrük beyanı ürün sayfasında doğru tanımlanmalıdır. Fiyatlar mağaza para biriminde listelenir; kur değiştikçe TL karşılığı değişir, bu yüzden kâr hesabı sipariş tarihindeki kurla yapılmalıdır. Etsy ücretleri (listeleme, işlem, ödeme işleme ve varsa reklam) komisyon yerine geçer ve kanal bazlı kâr hesabına ayrı kalemler olarak girer.
Stok tarafında, Etsy'de satılan ürün aynı anda Türkiye pazaryerlerinde de satılıyorsa senkron zorunludur; yurt dışı sipariş iptali hem satıcı performansını hem müşteri deneyimini daha ağır etkiler. Etsy ürünlerinde "işleme süresi" (processing time) de doğru girilmelidir; bu süre müşteriye gösterilir ve aşılması mağaza performansını etkiler.
- Kur: sipariş tarihindeki kurla kâr hesabı.
- Ücretler: listeleme + işlem + ödeme işleme (+ reklam).
- İşleme süresi ve kargo profili doğru tanımlı olsun.
Etsy ile Türkiye pazaryerlerinin farkı tek tabloda:
| Konu | Etsy | Türkiye pazaryerlerinin çoğu |
|---|---|---|
| Bağlantı | OAuth 2.0 onay ekranı; uygulama yalnızca onaylanan kapsamlarla erişir (Etsy entegrasyonu) | Panelden alınan API anahtarı yazılıma girilir |
| Ürün yapısı | Listing; varyasyonlar listing içinde, stok varyasyon kombinasyonu bazında tutulabilir | Barkod ya da stok koduyla tanımlanan ürün ve varyant |
| Eşleştirme anahtarı | Varyasyon SKU'su | Barkod ve stok kodu |
| Sipariş ve kargo | Sipariş receipt olarak gelir; takip numarası ve taşıyıcı API ile yazılır | Pazaryerinin anlaşmalı kargo firmaları |
| Para birimi | Mağaza para birimi; kâr sipariş tarihindeki kurla hesaplanır | TL |
| Ücretler | Listeleme, işlem, ödeme işleme (ve varsa reklam) | Kategoriye göre komisyon; kargo ve hizmet bedeli |
| Süre taahhüdü | İşleme süresi (processing time) | Kargoya verme (termin) süresi |
Bağlantıyı güvenli yönetmek
OAuth modeli, satıcının hangi uygulamanın mağazaya eriştiğini her zaman görmesine izin verir. Etsy hesap ayarlarında bağlı uygulamalar listelenir; artık kullanmadığınız bir aracı oradan kaldırın. Aynı mağazaya stok yazan iki ayrı uygulama birbirini ezer; tek bir stok yöneticisi kuralı burada da geçerlidir. Yetki yenileme ekranı geldiğinde (jeton süresi dolduğunda) bağlantıyı yeniden onaylamak dakikalar alır; bunu sabah rutininize ekleyin. Entegrasyon kavramlarının geneli için pazaryeri entegrasyonu nedir yazısı.
Etsy'yi Türkiye pazaryerleriyle aynı panelde yönetmek
Etsy'nin OAuth modeli, listing yapısı ve döviz işleyişi farklı olsa da satıcının günlük ihtiyacı aynıdır: stok tek yerden düşsün, siparişler tek listede görünsün, sorular tek yerden cevaplansın. Entegrasyon panelinde Etsy siparişi, Trendyol veya Hepsiburada siparişiyle yan yana durur; fark yalnızca para birimi ve kargo tipindedir. Kâr raporunda Etsy ücretleri kalem kalem, TL karşılığıyla görünmelidir; aksi hâlde yurt dışı kanal gerçekte olduğundan kârlı sanılır.
Etsy'de SKU disiplini kurulduğunda ürünleri Türkiye pazaryerleriyle eşleştirmek dakikalar alır ve aynı ürün iki pazarda güvenle satılır. Etsy'nin kendi dokümantasyonu (Open API v3 genel bakış) listing, stok ve sipariş kavramlarını tanımlar; entegrasyon paneli bu kavramları satıcı için ortak dile çevirir.
- Etsy siparişi tek listede, para birimi ve kargo tipi farklı.
- Etsy ücretleri kâr raporunda ayrı kalemler.
- SKU eşleşmesi → Türkiye pazaryerleriyle ortak stok.
Sık sorulan sorular
Etsy API anahtarımı nereden alırım?
Satıcı olarak anahtar almazsınız. Entegrasyon sağlayıcısının Etsy'de kayıtlı uygulaması vardır; siz yalnızca onay ekranında mağazanıza erişim izni verirsiniz.
Onayı iptal edersem ürünlerim silinir mi?
Hayır. İzin iptali yalnızca uygulamanın erişimini keser; ürün ve siparişleriniz Etsy'de aynen kalır.
Etsy'de stok senkronu diğer pazaryerlerinden farklı mı?
Mantık aynıdır; fark yetkilendirme (OAuth) ve ürün modelinde (listing ve varyasyon) ortaya çıkar. SKU tutarlılığı sağlanırsa senkron diğer kanallar gibi çalışır.