İstek alanları
| Alan | Tür | Açıklama |
|---|---|---|
| image | Dosya | Yüklenecek görsel dosyası |
| listing_image_id | Sayı | Daha önce silinmiş bir görseli yeniden bağlamak için |
| rank | Sayı | Sıra; 1 en soldaki ve ana görseldir |
| overwrite | Mantıksal | true ise aynı sıradaki görselin yerine geçer |
| is_watermarked | Mantıksal | Görselde filigran olduğunu belirtir |
| alt_text | Metin | Erişilebilirlik için alt metin; en fazla 500 karakter |
Etsy'ye göre image ve listing_image_id birlikte gönderilirse yalnız image yüklenir. Başarılı istek 201 ve bir ListingImage nesnesi döndürür.
Adım adım yükleme
- Taslak ilanı açın ve dönen listing_id değerini saklayın.
- Görsel dosyasını okuyun. Kaynağınız bir web adresiyse dosyayı önce kendi sunucunuza indirin.
- Her görsel için ayrı bir multipart isteği gönderin; rank değerini 1'den başlatın.
- Hız sınırına takılmamak için istekler arasına kısa bir bekleme koyun.
- Yükleme bittikten sonra ilanı yayına almak için updateListing ile state alanını active yapın.
Etsy belgesine göre yeni yüklenen görselin renk ve boyut bilgileri arka planda işlendiği için ilk yanıtta boş gelebilir. Bu değerlere ihtiyacınız varsa görseli birkaç saniye sonra yeniden okuyun.
Görselleri okuma
Tek ilanın görselleri GET /v3/application/listings/{listing_id}/images ucundan gelir. Çok sayıda ilan okuyorsanız mağaza ilan listesini includes=Images ile istemek, ilan başına ayrı görsel isteğini ortadan kaldırır.
| Yanıt alanı | Boyut |
|---|---|
| url_75x75 | 75x75 küçük görsel |
| url_170x135 | 170x135 küçük görsel |
| url_570xN | En fazla 570 piksel genişlik |
| url_fullxfull | Tam boyut; her kenar en fazla 3000 piksel |
Bir görseli kaldırmak için DELETE .../shops/{shop_id}/listings/{listing_id}/images/{listing_image_id} ucu kullanılır. Etsy, silinen görselin kimliğiyle sonradan aynı ilana yeniden bağlanmasına izin verir. Varyasyona özel görseller ise ayrı bir uçla, .../listings/{listing_id}/variation-images adresinden yönetilir.
Sık hatalar
- Görsel adresi gönderildi: image alanı dosya bekler. Adresi indirip dosya olarak gönderin.
- İçerik türü elle yazıldı: multipart isteğinde sınır (boundary) bilgisini kütüphane ekler. Başlığı elle sabitlemek isteği bozabilir.
- Yirmiden fazla görsel: Etsy bir ilanda en fazla 20 görsel kimliği kabul eder.
- İlan yayına alınamıyor: taslakta hiç görsel yoksa active durumuna geçilemez.
Sık sorulanlar
Etsy API görsel URL kabul ediyor mu?
Hayır. uploadListingImage ucunun image alanı dosya ister. Görseli önce indirip multipart/form-data ile gönderirsiniz.
Etsy ilanına kaç görsel eklenebilir?
Etsy ilan alanlarında image_ids için en fazla 20 görsel belirtir. Ayrıca bir ilanda en fazla iki etkin video bulunabilir.
Ana görsel nasıl belirlenir?
rank değeri 1 olan görsel en soldaki, yani ana görseldir. Var olan bir sıranın yerine yükleme yapmak için overwrite=true gönderin.
Yüklenen görselin renk bilgisi neden boş?
Etsy görseli arka planda işler; renk ve boyut alanları ilk yanıtta boş gelebilir. Birkaç saniye sonra görseli tek görsel ucundan yeniden okuyun.
Kaynaklar
İlgili Etsy API konuları
Son güncelleme: 27.10.2026 · Etsy API rehberinin tamamı