İki token, iki süre
| Token | Süre | Ne için | Not |
|---|---|---|---|
| access_token | 1 saat (expires_in: 3600) | Her API isteğinde Authorization: Bearer başlığı | Başında kullanıcı kimliği ve nokta bulunur |
| refresh_token | 90 gün | Yeni erişim token'ı almak | İlk izindeki kapsamı taşır, kapsam değiştirilemez |
Kapsamı genişletmek isterseniz yenileme yetmez. Etsy'ye göre kapsam değişikliği için yetkilendirme akışının baştan yapılması gerekir (Etsy: Authentication).
Yenileme isteği
Yenileme de yetkilendirme koduyla aynı adrese, application/x-www-form-urlencoded gövdeyle yapılan bir POST isteğidir. Gövdede üç alan bulunur:
- grant_type: refresh_token
- client_id: KEYSTRING
- refresh_token: KULLANICI_ID.YENILEME_TOKENI
Yanıt, ilk token isteğiyle aynı alanları içerir: access_token, token_type, expires_in, refresh_token ve scope. Yeni erişim token'ının süresi expires_in ile gelir; süreyi sabit 3600 varsaymak yerine bu alandan hesaplayın.
Yeni refresh token'ı mutlaka saklayın
Yenileme yanıtındaki refresh_token değeri bir sonraki yenilemede kullanılacak değerdir. Canlı kullanımda bu değerin yenilemelerde değiştiği, eski değerin ise bir süre sonra "refresh_token is invalid" hatası verdiği görüldü.
En sık hata, yeni değeri yalnız bellekte tutmaktır. Sunucu ya da işlem yeniden başladığında eski değer okunur ve bağlantı kopar. Yeni değeri her yenilemeden sonra şifreli olarak kalıcı depoya yazın; birden fazla sunucu aynı mağaza için çalışıyorsa yenilemeyi tek bir yerde yapın.
Ne zaman yenilemeli?
- Erişim token'ını süresi dolmadan kısa bir pay bırakarak yenileyin; böylece uzun süren bir toplu işlem yarıda kalmaz.
- Bir istek 401 dönerse önce token'ı yenileyip isteği bir kez tekrarlayın; ikinci 401'de durup kimlik bilgilerini kontrol edin.
- 90 günlük süre dolmadan önce bağlantıyı düzenli kullanın ya da satıcıdan yeniden izin isteyin.
- Satıcı uygulamanın erişimini kaldırırsa yenileme de başarısız olur; tek çözüm yeni bir yetkilendirmedir.
Sık hatalar ve çözümleri
| Belirti | Olası neden | Çözüm |
|---|---|---|
| "refresh_token is invalid" | Eski ya da süresi dolmuş değer kullanıldı | En son saklanan değeri kullanın; yoksa yetkilendirmeyi yenileyin |
| Token alındı ama istekler 401 | x-api-key başlığı eksik ya da yanlış | Her istekte KEYSTRING:SHARED_SECRET gönderin |
| Bazı uçlar 403 | Token'da gereken kapsam yok | Eksik kapsamla akışı baştan yapın |
| Eski v2 token'ı çalışmıyor | v3 yalnız OAuth 2.0 token'ı kabul eder | Etsy'nin token_exchange akışıyla dönüştürün |
Sık sorulanlar
Etsy access token ne kadar geçerli?
Bir saat. Token yanıtındaki expires_in alanı saniye cinsinden süreyi verir; Etsy örneğinde bu değer 3600'dür.
Etsy refresh token süresi ne kadar?
Etsy belgesine göre refresh token 90 gün kullanılabilir. Yenileme yanıtıyla gelen yeni değeri saklayıp bir sonraki yenilemede onu kullanın.
Yenileme ile yeni izin ekleyebilir miyim?
Hayır. Yenilenen token ilk izindeki kapsamı taşır. Yeni bir kapsam için satıcının izin sayfasından yeniden geçmesi gerekir.
"refresh_token is invalid" hatası neden çıkar?
Çoğunlukla kayıtlı değer günceli değildir; yenilemede gelen yeni token saklanmamıştır. Süre dolması ya da satıcının erişimi kaldırması da aynı sonucu verir. Bu durumda yetkilendirmeyi baştan yapın.
Kaynaklar
İlgili Etsy API konuları
Son güncelleme: 27.10.2026 · Etsy API rehberinin tamamı