Etsy API Kullanımı: Kapsamlı Entegrasyon Rehberi (2026)

KISA BİLGİ

Etsy API, geliştiricilerin Etsy pazar yeriyle etkileşim kuran uygulamalar oluşturmasına olanak tanır. OAuth 2.0 kimlik doğrulamasını, mağazalar, listelemeler, siparişler ve envanter yönetimi için RESTful uç noktaları kullanır ve uygulama başına saniyede 10 çağrı hız limiti vardır. Bu kılavuz, kimlik doğrulama kurulumunu, temel uç noktaları, webhook entegrasyonunu ve üretim dağıtım stratejilerini kapsar.

Giriş

Etsy, 230'dan fazla ülkede yılda 13 milyar doların üzerinde brüt mal satışı gerçekleştirmektedir. E-ticaret araçları, envanter yönetim sistemleri veya analiz platformları geliştiren geliştiriciler için Etsy API entegrasyonu isteğe bağlı değil, zorunludur.

Gerçek şu ki: birden fazla satış kanalını yöneten satıcılar, manuel veri girişi yüzünden haftada 15-20 saat kaybediyorlar. Sağlam bir Etsy API entegrasyonu, listeleme senkronizasyonunu, sipariş işlemeyi ve platformlar arası envanter güncellemelerini otomatikleştirir.

Bu kılavuz, eksiksiz Etsy API entegrasyon sürecini adım adım anlatır. OAuth 2.0 kimlik doğrulamasını, mağaza ve listeleme yönetimini, sipariş işlemeyi, webhook işlemeyi ve hata gidermeyi öğreneceksiniz. Sonunda, üretime hazır bir Etsy entegrasyonuna sahip olacaksınız.

Etsy API Nedir?

Etsy, pazar yeri verilerine erişmek ve satıcı operasyonlarını yönetmek için bir RESTful API sağlar. API şunları yönetir:

• Mağaza ve profil bilgilerini alma
• Listeleme oluşturma, güncelleme ve envanter yönetimi
• Sipariş işleme ve gönderi takibi
• Müşteri ve işlem verilerine erişim
• Kargo profilleri ve vergi hesaplamaları
• Görsel ve medya yükleme yönetimi

Temel Özellikler

API Mimarisinin Genel Görünümü

Etsy, sürüm kontrollü bir REST API yapısı kullanır:

https://openapi.etsy.com/v3/application/

Sürüm 3 (v3) mevcut standarttır ve v2'ye kıyasla geliştirilmiş OAuth 2.0 desteği ve basitleştirilmiş uç nokta yapıları sunar.

API Sürümlerinin Karşılaştırması

Tüm V2 entegrasyonlarını derhal V3'e taşıyın. Etsy, V2'nin kullanımdan kaldırıldığını ve tam olarak 2026 sonlarında sona ereceğini duyurdu.

Başlarken: Kimlik Doğrulama Kurulumu

Adım 1: Etsy Geliştirici Hesabınızı Oluşturun

API'ye erişmeden önce bir geliştirici hesabına ihtiyacınız var:

1. Etsy Geliştirici Portalı'nı ziyaret edin
2. Etsy hesabınızla oturum açın (veya yeni bir hesap oluşturun)
3. Geliştirici panosundaki Uygulamalarınız bölümüne gidin
4. Yeni bir uygulama oluştur'a tıklayın

Adım 2: Uygulamanızı Kaydedin

Uygulama kayıt formunu doldurun:

• Uygulama Adı: Net, açıklayıcı ad (OAuth sırasında kullanıcılara görünür)
• Uygulama Açıklaması: Uygulamanızın ne yaptığını ve kimlerin kullandığını açıklayın
• Yönlendirme URI'si: Etsy'nin kimlik doğrulamadan sonra kullanıcıları nereye göndereceği (HTTPS kullanmalıdır)
• Üretim/Geliştirme: Test için geliştirme moduyla başlayın

Gönderdikten sonra şunları alacaksınız:

• Anahtar Dizini (Key String): Genel API tanımlayıcınız
• Paylaşılan Gizli Anahtar (Shared Secret): Özel API sırrınız (bunu asla açığa çıkarmayın)

Güvenlik notu: Kimlik bilgilerini kodda değil, ortam değişkenlerinde saklayın:

# .env dosyası
ETSY_KEY_STRING="anahtar_dizininiz_buraya"
ETSY_SHARED_SECRET="paylaşılan_gizli_anahtarınız_buraya"
ETSY_ACCESS_TOKEN="oauth_ile_oluşturuldu"
ETSY_REFRESH_TOKEN="oauth_ile_oluşturuldu"

Adım 3: OAuth 2.0 Akışını Anlayın

Etsy, kimlik doğrulama için OAuth 2.0 kullanır. İşte tam akış:

1. Kullanıcı uygulamanızda "Etsy ile Bağlan"a tıklar
2. Uygulamanız Etsy yetkilendirme URL'sine yönlendirir
3. Kullanıcı giriş yapar ve izinleri verir
4. Etsy yetkilendirme koduyla geri yönlendirir
5. Uygulamanız kodu erişim belirteciyle değiştirir
6. Uygulamanız API çağrıları için erişim belirtecini kullanır
7. Erişim belirteci süresi dolduğunda (1 saat) yenileme belirtecini kullanır

Adım 4: OAuth Yetkilendirmeyi Uygulayın

Yetkilendirme URL'sini oluşturun:

const generateAuthUrl = (clientId, redirectUri, state) => {
  const baseUrl = 'https://www.etsy.com/oauth/connect';
  const params = new URLSearchParams({
    client_id: clientId,
    redirect_uri: redirectUri,
    scope: 'listings_r listings_w orders_r orders_w shops_r',
    state: state, // CSRF koruması için rastgele dize
    response_type: 'code'
  });

  return `${baseUrl}?${params.toString()}`;
};

// Kullanım
const authUrl = generateAuthUrl(
  process.env.ETSY_KEY_STRING,
  'https://uygulamanız.com/geri_dönüş',
  crypto.randomBytes(16).toString('hex')
);

console.log(`Kullanıcıyı şuraya yönlendir: ${authUrl}`);

Gerekli Kapsamlar (Scopes)

Yalnızca uygulamanızın ihtiyaç duyduğu izinleri isteyin:

Adım 5: Kodu Erişim Belirteciyle Değiştirin

OAuth geri aramasını işleyin ve yetkilendirme kodunu değiştirin:

const exchangeCodeForToken = async (code, redirectUri) => {
  const response = await fetch('https://api.etsy.com/v3/public/oauth/token', {
    method: 'POST',
    headers: {
      'Accept': 'application/json',
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      client_id: process.env.ETSY_KEY_STRING,
      client_secret: process.env.ETSY_SHARED_SECRET,
      redirect_uri: redirectUri,
      code: code
    })
  });

  const data = await response.json();

  // Bunları güvenli bir şekilde veritabanınızda saklayın
  return {
    access_token: data.access_token,
    refresh_token: data.refresh_token,
    expires_in: data.expires_in, // Genellikle 3600 saniye (1 saat)
    user_id: data.user_id,
    scope: data.scope
  };
};

// Geri arama rotasını işleyin
app.get('/geri_dönüş', async (req, res) => {
  const { code, state } = req.query;

  // Gönderdiğiniz state ile eşleştiğini doğrulayın (CSRF koruması)
  if (state !== req.session.oauthState) {
    return res.status(400).send('Geçersiz state parametresi');
  }

  try {
    const tokens = await exchangeCodeForToken(code, 'https://uygulamanız.com/geri_dönüş');

    // Belirteçleri kullanıcıyla ilişkili olarak veritabanında saklayın
    await db.users.update(req.session.userId, {
      etsy_access_token: tokens.access_token,
      etsy_refresh_token: tokens.refresh_token,
      etsy_token_expires: Date.now() + (tokens.expires_in * 1000),
      etsy_user_id: tokens.user_id
    });

    res.redirect('/kontrol_paneli');
  } catch (error) {
    console.error('Belirteç değişimi başarısız oldu:', error);
    res.status(500).send('Kimlik doğrulama başarısız oldu');
  }
});

Adım 6: Belirteç Yenilemeyi Uygulayın

Erişim belirteçleri 1 saat sonra sona erer. Otomatik yenilemeyi uygulayın:

const refreshAccessToken = async (refreshToken) => {
  const response = await fetch('https://api.etsy.com/v3/public/oauth/token', {
    method: 'POST',
    headers: {
      'Accept': 'application/json',
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: new URLSearchParams({
      grant_type: 'refresh_token',
      client_id: process.env.ETSY_KEY_STRING,
      client_secret: process.env.ETSY_SHARED_SECRET,
      refresh_token: refreshToken
    })
  });

  const data = await response.json();

  // Saklanan belirteçleri güncelleyin
  return {
    access_token: data.access_token,
    refresh_token: data.refresh_token, // Her zaman yeni yenileme belirtecini kaydedin
    expires_in: data.expires_in
  };
};

// API çağrılarından önce geçerli belirteci sağlamak için ara yazılım
const ensureValidToken = async (userId) => {
  const user = await db.users.findById(userId);

  // Belirtecin 5 dakika içinde süresinin dolup dolmadığını kontrol edin
  if (user.etsy_token_expires < Date.now() + 300000) {
    const newTokens = await refreshAccessToken(user.etsy_refresh_token);

    await db.users.update(userId, {
      etsy_access_token: newTokens.access_token,
      etsy_refresh_token: newTokens.refresh_token,
      etsy_token_expires: Date.now() + (newTokens.expires_in * 1000)
    });

    return newTokens.access_token;
  }

  return user.etsy_access_token;
};

Adım 7: Kimliği Doğrulanmış API Çağrıları Yapın

Her isteğe erişim belirtecini ekleyin:

const makeEtsyRequest = async (endpoint, options = {}) => {
  const accessToken = await ensureValidToken(options.userId);

  const response = await fetch(`https://openapi.etsy.com/v3/application${endpoint}`, {
    ...options,
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'x-api-key': process.env.ETSY_KEY_STRING,
      'Accept': 'application/json',
      'Content-Type': 'application/json',
      ...options.headers
    }
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Etsy API Hatası: ${error.message}`);
  }

  return response.json();
};

Mağaza Yönetimi Uç Noktaları

Mağaza Bilgilerini Alma

Mağaza ayrıntılarını, politikalarını ve ayarlarını getirin:

const getShopInfo = async (shopId) => {
  const response = await makeEtsyRequest(`/shops/${shopId}`, {
    method: 'GET'
  });

  return response;
};

// Kullanım
const shop = await getShopInfo(12345678);
console.log(`Mağaza: ${shop.title}`);
console.log(`Para Birimi: ${shop.currency_code}`);
console.log(`Listeleme sayısı: ${shop.num_listings_active}`);

Beklenen Mağaza Yanıtı

{
  "shop_id": 12345678,
  "shop_name": "ElYapımıDükkanım",
  "title": "El Yapımı Takı ve Aksesuarlar",
  "announcement": "Hoş geldiniz! 50 dolar üzeri siparişlerde ücretsiz kargo",
  "currency_code": "USD",
  "is_vacation": false,
  "vacation_message": null,
  "sale_message": "Küçük işletmeleri desteklediğiniz için teşekkür ederiz!",
  "digital_sale_message": null,
  "created_timestamp": 1609459200,
  "updated_timestamp": 1710950400,
  "num_listings_active": 127,
  "num_listings_sold": 1543,
  "gaussian_alphas": {
    "overall": 4.8,
    "last_30_days": 4.9
  },
  "vacation_autoreply": null,
  "url": "https://www.etsy.com/shop/ElYapımıDükkanım",
  "image_url_760x100": "https://i.etsystatic.com/.../banner_760x100.jpg"
}

Mağaza Bölümlerini Alma

Listelemeleri bölümlere göre düzenleyin:

const getShopSections = async (shopId) => {
  const response = await makeEtsyRequest(`/shops/${shopId}/sections`, {
    method: 'GET'
  });

  return response;
};

// Örnek yanıt
{
  "count": 5,
  "results": [
    {
      "shop_section_id": 12345,
      "title": "Kolyeler",
      "rank": 1,
      "num_listings": 23
    },
    {
      "shop_section_id": 12346,
      "title": "Küpe",
      "rank": 2,
      "num_listings": 45
    }
  ]
}

Listeleme Yönetimi

Yeni Bir Listeleme Oluşturma

Görseller ve varyasyonlarla bir ürün listelemesi oluşturun:

const createListing = async (shopId, listingData) => {
  const payload = {
    title: listingData.title,
    description: listingData.description,
    price: listingData.price.toString(), // Dize olmalı
    quantity: listingData.quantity,
    sku: listingData.sku || [],
    tags: listingData.tags.slice(0, 13), // Maksimum 13 etiket
    category_id: listingData.categoryId,
    shop_section_id: listingData.sectionId,
    state: listingData.state || 'active', // active, inactive, draft
    who_made: listingData.whoMade, // i_did, someone_else, collective
    when_made: listingData.whenMade, // 2020_2026, 2010_2019, vb.
    is_supply: listingData.isSupply, // El işi malzemeleri için true
    item_weight: listingData.weight || null,
    item_weight_unit: listingData.weightUnit || 'g',
    item_length: listingData.length || null,
    item_width: listingData.width || null,
    item_height: listingData.height || null,
    item_dimensions_unit: listingData.dimensionsUnit || 'mm',
    is_private: listingData.isPrivate || false,
    recipient: listingData.recipient || null, // erkekler, kadınlar, unisex, vb.
    occasion: listingData.occasion || null, // doğum günü, düğün, vb.
    style: listingData.style || [] // Maksimum 2 stil
  };

  const response = await makeEtsyRequest(`/shops/${shopId}/listings`, {
    method: 'POST',
    body: JSON.stringify(payload)
  });

  return response;
};

// Kullanım örneği
const listing = await createListing(12345678, {
  title: 'Ay Fazı Kolye Gümüş',
  description: 'El yapımı gümüş ay fazı kolye...',
  price: 89.99,
  quantity: 15,
  sku: ['AY-KOLYE-001'],
  tags: ['ay kolye', 'gümüş', 'ay fazı', 'göksel takı'],
  categoryId: 10623, // Takı > Kolyeler
  sectionId: 12345,
  state: 'active',
  whoMade: 'i_did',
  whenMade: 'made_to_order',
  isSupply: false,
  weight: 25,
  weightUnit: 'g'
});

Listeleme Görsellerini Yükleme

Görseller listeleme oluşturulduktan sonra ayrı olarak yüklenir:

const uploadListingImage = async (listingId, imagePath, imagePosition = 1) => {
  // Görsel dosyasını base64 olarak okuyun
  const fs = require('fs');
  const imageBuffer = fs.readFileSync(imagePath);
  const base64Image = imageBuffer.toString('base64');

  const payload = {
    image: base64Image,
    listing_image_id: null,
    position: imagePosition,
    is_watermarked: false,
    alt_text: 'El yapımı gümüş ay fazı kolye' // Erişilebilirlik için
  };

  const response = await makeEtsyRequest(`/listings/${listingId}/images`, {
    method: 'POST',
    body: JSON.stringify(payload)
  });

  return response;
};

// Birden fazla görsel yükle
const uploadListingImages = async (listingId, imagePaths) => {
  const results = [];

  for (let i = 0; i < imagePaths.length; i++) {
    const result = await uploadListingImage(listingId, imagePaths[i], i + 1);
    results.push(result);
  }

  return results;
};

Listeleme Envanterini Güncelleme

Mevcut listelemeler için miktarı güncelleyin:

const updateListingInventory = async (shopId, listingId, inventory) => {
  const payload = {
    products: inventory.products.map(product => ({
      sku: product.sku,
      quantity: product.quantity
    })),
    is_over_selling: inventory.isOverSelling || false,
    on_property: inventory.onProperty || []
  };

  const response = await makeEtsyRequest(
    `/shops/${shopId}/listings/${listingId}/inventory`,
    {
      method: 'PUT',
      body: JSON.stringify(payload)
    }
  );

  return response;
};

// Kullanım
await updateListingInventory(12345678, 987654321, {
  products: [
    { sku: 'AY-KOLYE-001', quantity: 10 },
    { sku: 'AY-KOLYE-002', quantity: 5 }
  ],
  isOverSelling: false
});

Listelemeleri Alma

Tüm listelemeleri getirin veya duruma göre filtreleyin:

const getListings = async (shopId, options = {}) => {
  const params = new URLSearchParams({
    limit: options.limit || 25, // Maksimum 100
    offset: options.offset || 0
  });

  if (options.state) {
    params.append('state', options.state); // active, inactive, draft, sold_out
  }

  const response = await makeEtsyRequest(
    `/shops/${shopId}/listings?${params.toString()}`,
    { method: 'GET' }
  );

  return response;
};

// Tek bir listelemeyi al
const getListing = async (listingId) => {
  const response = await makeEtsyRequest(`/listings/${listingId}`, {
    method: 'GET'
  });

  return response;
};

Bir Listelemeyi Silme

Mağazanızdan bir listelemeyi kaldırın:

const deleteListing = async (listingId) => {
  const response = await makeEtsyRequest(`/listings/${listingId}`, {
    method: 'DELETE'
  });

  return response;
};

Sipariş Yönetimi

Siparişleri Alma

Filtreleme seçenekleriyle siparişleri getirin:

const getOrders = async (shopId, options = {}) => {
  const params = new URLSearchParams({
    limit: options.limit || 25,
    offset: options.offset || 0
  });

  if (options.status) {
    params.append('status', options.status); // open, completed, cancelled
  }

  if (options.minLastModified) {
    params.append('min_last_modified', options.minLastModified);
  }

  const response = await makeEtsyRequest(
    `/shops/${shopId}/orders?${params.toString()}`,
    { method: 'GET' }
  );

  return response;
};

// Tek bir siparişi al
const getOrder = async (shopId, orderId) => {
  const response = await makeEtsyRequest(`/shops/${shopId}/orders/${orderId}`, {
    method: 'GET'
  });

  return response;
};

Sipariş Yanıt Yapısı

{
  "order_id": 1234567890,
  "user_id": 98765432,
  "shop_id": 12345678,
  "buyer_user_id": 11223344,
  "creation_timestamp": 1710864000,
  "last_modified_timestamp": 1710950400,
  "completed_timestamp": 1710950400,
  "state": "complete",
  "user_id_fob": null,
  "is_guest": false,
  "name": "Ayşe Yılmaz",
  "email": "ayse.yilmaz@eposta.com",
  "buyer_phone_number": "+90-555-1234",
  "total_price": "89.99",
  "total_shipping_cost": "5.95",
  "total_tax": "7.65",
  "grand_total": "103.59",
  "currency_code": "USD",
  "payment_method": "credit_card",
  "shipping_address": {
    "name": "Ayşe Yılmaz",
    "address_line1": "Ana Cadde 123",
    "address_line2": "Daire 4B",
    "city": "İstanbul",
    "state": "TR",
    "zip": "34000",
    "country": "TR",
    "phone": "+90-555-1234"
  },
  "listings": [
    {
      "listing_id": 987654321,
      "title": "Ay Fazı Kolye Gümüş",
      "sku": ["AY-KOLYE-001"],
      "quantity": 1,
      "price": "89.99"
    }
  ]
}

Sipariş Durumunu Güncelleme

Siparişleri tamamlandı olarak işaretleyin ve takip ekleyin:

const updateOrderStatus = async (shopId, orderId, trackingData) => {
  const payload = {
    carrier_id: trackingData.carrierId, // ptt, fedex, ups, vb.
    tracking_code: trackingData.trackingCode,
    should_send_bcc_to_buyer: trackingData.notifyBuyer || true
  };

  const response = await makeEtsyRequest(
    `/shops/${shopId}/orders/${orderId}/shipping`,
    {
      method: 'POST',
      body: JSON.stringify(payload)
    }
  );

  return response;
};

// Kullanım
await updateOrderStatus(12345678, 1234567890, {
  carrierId: 'ptt',
  trackingCode: '9400111899223456789012',
  notifyBuyer: true
});

Yaygın Taşıyıcı Kimlikleri

Hız Sınırlandırma ve Kotalar

Hız Sınırlarını Anlamak

Etsy, API kararlılığını korumak için hız sınırları uygular:

• Standart Sınır: Uygulama başına saniyede 10 istek
• Anlık İzin: Tek bir saniyede 50 isteğe kadar (kısa anlık artışlar)
• Kota Sistemi: Uygulama başına saatte 10.000 çağrı (saatlik olarak sıfırlanır)

Sınırların aşılması HTTP 429 (Çok Fazla İstek) yanıtlarıyla sonuçlanır.

Hız Sınırı İşlemesini Uygulama

Yeniden denemeler için üstel geri çekilme kullanın:

const makeRateLimitedRequest = async (endpoint, options = {}, maxRetries = 3) => {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await makeEtsyRequest(endpoint, options);

      // Hız limiti başlıklarını kontrol edin
      const remaining = response.headers.get('x-etsy-quota-remaining');
      const resetTime = response.headers.get('x-etsy-quota-reset');

      if (remaining < 100) {
        console.warn(`Kalan kota düşük: ${remaining}, ${resetTime} tarihinde sıfırlanır`);
      }

      return response;
    } catch (error) {
      if (error.message.includes('429') && attempt < maxRetries) {
        // Üstel geri çekilme: 1s, 2s, 4s
        const delay = Math.pow(2, attempt) * 1000;
        console.log(`Hız limiti aşıldı. ${delay}ms sonra tekrar deniyor...`);
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        throw error;
      }
    }
  }
};

Hız Sınırı Başlıkları

Etsy, her yanıtta bu başlıkları içerir:

İzleme ve hata ayıklama için bu başlıkları her zaman günlüğe kaydedin.

Webhook Entegrasyonu

Web Kancalarını Yapılandırma

Etsy, gerçek zamanlı olay bildirimleri için web kancalarını destekler:

1. Geliştirici panosundaki Uygulamalarınız bölümüne gidin
2. Uygulamanızı seçin
3. Web Kancası Ekle'ye tıklayın
4. HTTPS uç nokta URL'nizi girin
5. Abone olunacak olayları seçin

Mevcut Web Kancası Olayları

Web Kancası İşleyici Oluşturma

const express = require('express');
const crypto = require('crypto');
const app = express();

app.post('/webhooks/etsy', express.raw({ type: 'application/json' }), async (req, res) => {
  const signature = req.headers['x-etsy-signature'];
  const payload = req.body;

  // Web kancası imzasını doğrula
  const isValid = verifyWebhookSignature(payload, signature, process.env.ETSY_WEBHOOK_SECRET);

  if (!isValid) {
    console.error('Geçersiz web kancası imzası');
    return res.status(401).send('Yetkisiz');
  }

  const event = JSON.parse(payload.toString());

  // Uygun işleyiciye yönlendir
  switch (event.type) {
    case 'v3/shops/*/orders/create':
      await handleNewOrder(event.data);
      break;
    case 'v3/shops/*/orders/update':
      await handleOrderUpdate(event.data);
      break;
    case 'v3/shops/*/listings/create':
      await handleListingCreated(event.data);
      break;
    case 'v3/shops/*/listings/update':
      await handleListingUpdated(event.data);
      break;
    case 'v3/shops/*/listings/delete':
      await handleListingDeleted(event.data);
      break;
    default:
      console.log('İşlenmeyen olay türü:', event.type);
  }

  // 5 saniye içinde alındığını bildir
  res.status(200).send('Tamam');
});

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

Web Kancası En İyi Uygulamaları

1. İmzaları doğrulayın - Sahte web kancalarını önler
2. Hızla 200 OK döndürün - Etsy, 5 saniye içinde 200 olmayan yanıtlarda tekrar dener
3. Eşzamansız işleyin - Arka plan işleme için olayları kuyruğa alın
4. İdempotensi uygulayın - Yinelenen web kancası teslimatlarını işleyin
5. Tüm olayları günlüğe kaydedin - Zaman damgalı denetim izi ile sorunları giderin

Yaygın Sorun Giderme

Sorun: OAuth Belirteç Değişimi Başarısız Oluyor

Belirtiler: Kimlik doğrulama sırasında 401 veya 403 hataları alınıyor.

Teşhis:

// Hata yanıtını kontrol edin
const error = await response.json();
console.error('OAuth hatası:', error);

Çözümler:

1. Yönlendirme URI'sinin tam olarak eşleştiğini doğrulayın (https:// ve sondaki eğik çizgi dahil)
2. client_id ve client_secret'ın doğru olduğunu onaylayın
3. Yetkilendirme kodunun süresinin dolmadığından emin olun (kodlar 1 kullanım veya 5 dakika sonra sona erer)
4. Uygulamanın üretim modunda olduğunu kontrol edin (geliştirme uygulamaları yalnızca test hesaplarına erişebilir)

Sorun: Hız Limiti Aşıldı

Belirtiler: HTTP 429 yanıtları alınıyor.

Çözümler:

1. Hız sınırlama ile istek kuyruklamasını uygulayın
2. Yeniden denemeler için üstel geri çekilme kullanın
3. Mümkün olduğunca istekleri toplu işleyin (örneğin, tek bir çağrıda birden fazla listeleme alın)
4. Kota başlıklarını izleyin ve proaktif olarak kısıtlayın

// Basit hız sınırlayıcı
class RateLimiter {
  constructor(requestsPerSecond = 9) { // Saniyede 10 isteğin altında kalın
    this.queue = [];
    this.interval = 1000 / requestsPerSecond;
    this.processing = false;
  }

  async add(requestFn) {
    return new Promise((resolve, reject) => {
      this.queue.push({ requestFn, resolve, reject });
      this.process();
    });
  }

  async process() {
    if (this.processing || this.queue.length === 0) return;

    this.processing = true;

    while (this.queue.length > 0) {
      const { requestFn, resolve, reject } = this.queue.shift();

      try {
        const result = await requestFn();
        resolve(result);
      } catch (error) {
        reject(error);
      }

      if (this.queue.length > 0) {
        await new Promise(r => setTimeout(r, this.interval));
      }
    }

    this.processing = false;
  }
}

// Kullanım
const etsyRateLimiter = new RateLimiter(9);
const result = await etsyRateLimiter.add(() => makeEtsyRequest('/shops/12345/listings'));

Sorun: Listeleme Oluşturma Doğrulama Hatalarıyla Başarısız Oluyor

Belirtiler: Doğrulama hata mesajlarıyla 400 Hatalı İstek.

Yaygın Nedenler:

1. Geçersiz category_id: Geçerli kimlikleri almak için Etsy'nin kategoriler API'sini kullanın
2. Fiyat biçimi: Sayı değil, dize olmalı
3. Etiket sınırı: Listeleme başına maksimum 13 etiket
4. Gerekli alanlar eksik: title, description, price, quantity, who_made, when_made

Çözüm:

// Göndermeden önce doğrula
const validateListing = (data) => {
  const errors = [];

  if (!data.title || data.title.length < 5) {
    errors.push('Başlık en az 5 karakter olmalıdır');
  }

  if (typeof data.price !== 'string') {
    errors.push('Fiyat dize olmalıdır');
  }

  if (data.tags && data.tags.length > 13) {
    errors.push('Maksimum 13 etiket izin verilir');
  }

  if (!['i_did', 'someone_else', 'collective'].includes(data.whoMade)) {
    errors.push('Geçersiz who_made değeri');
  }

  return errors;
};

Sorun: Web Kancaları Gelmiyor

Belirtiler: Siparişler işleniyor ancak web kancası uç noktasına hiçbir şey gelmiyor.

Teşhis:

1. Geliştirici panosunda web kancası teslimat günlüklerini kontrol edin
2. Uç noktanın 5 saniye içinde 200 OK döndürdüğünü doğrulayın
3. Uç noktayı curl ile manuel olarak test edin

Çözümler:

1. Geçerli SSL sertifikasıyla HTTPS kullandığınızdan emin olun
2. Güvenlik duvarında Etsy web kancası IP'lerini beyaz listeye alın
3. İmza doğrulama mantığını kontrol edin
4. Geliştirme sırasında web kancası test araçlarını kullanın

Sorun: Görsel Yüklenemiyor

Belirtiler: Listeleme oluşturuluyor ancak görseller hata döndürüyor.

Çözümler:

1. Görselin geçerli biçimde (JPEG, PNG, GIF) olduğunu doğrulayın
2. Dosya boyutunu kontrol edin (görsel başına maksimum 20MB)
3. Base64 kodlamanın doğru olduğundan emin olun
4. Görselleri yüklemeden önce listelemenin mevcut olduğunu onaylayın
5. Görselleri paralel değil, sıralı olarak yükleyin

Üretim Dağıtım Kontrol Listesi

Canlıya geçmeden önce:

• [ ] Geliştirmeden üretim uygulama moduna geçiş yapın
• [ ] Tüm yönlendirme URI'lerini üretim URL'lerine güncelleyin
• [ ] Güvenli belirteç depolamayı uygulayın (şifreli veritabanı)
• [ ] Otomatik belirteç yenileme mantığını ekleyin
• [ ] Hız sınırlama ve istek kuyruklamasını ayarlayın
• [ ] Web kancası uç noktasını HTTPS ile yapılandırın
• [ ] Kapsamlı hata işlemeyi uygulayın
• [ ] Tüm API çağrıları için günlük kaydı ekleyin
• [ ] Kota kullanımı için izlemeyi ayarlayın
• [ ] Yaygın sorunlar için bir runbook oluşturun
• [ ] Birden fazla mağaza hesabıyla test edin
• [ ] Kullanıcı katılımı için OAuth akışını belgeleyin

İzleme ve Uyarı

Bu metrikleri izleyin:

// İzlenecek örnek metrikler
const metrics = {
  apiCalls: {
    total: 0,
    successful: 0,
    failed: 0,
    rateLimited: 0
  },
  quotaUsage: {
    current: 0,
    limit: 10000,
    resetTime: null
  },
  oauthTokens: {
    active: 0,
    expiring_soon: 0,
    refresh_failures: 0
  },
  webhooks: {
    received: 0,
    processed: 0,
    failed: 0
  }
};

// Yüksek hata oranında uyarı
const failureRate = metrics.apiCalls.failed / metrics.apiCalls.total;

if (failureRate > 0.05) { // %5'ten fazla hata oranı
  sendAlert('Etsy API hata oranı %5 üzerinde');
}

// Düşük kota durumunda uyarı
if (metrics.quotaUsage.current < 500) {
  sendAlert('Etsy API kotası 500 çağrıdan daha az kaldı');
}

Gerçek Dünya Kullanım Durumları

Çok Kanallı Envanter Senkronizasyonu

Bir ev dekorasyonu satıcısı, Etsy API'sini kullanarak Etsy, Shopify ve Amazon'daki envanteri senkronize ediyor:

• Zorluk: Manuel envanter güncellemeleri aşırı satışlara yol açıyordu
• Çözüm: Etsy API web kancaları ile merkezi envanter sistemi
• Sonuç: Sıfır aşırı satış olayı, haftada 12 saat zaman tasarrufu

Uygulama akışı:

1. Etsy web kancası sipariş oluşturma üzerinde tetiklenir
2. Merkezi sistem envanteri azaltır
3. API çağrıları Shopify ve Amazon miktarlarını günceller
4. Onay veritabanına kaydedilir

Otomatik Sipariş Karşılama

Bir talep üzerine baskı işi sipariş işlemeyi otomatikleştirir:

• Zorluk: Günde 50'den fazla sipariş manuel veri girişi gerektiriyordu
• Çözüm: Gönderim sağlayıcısıyla Etsy API entegrasyonu
• Sonuç: Siparişler 5 dakika içinde üretime otomatik olarak yönlendirildi

Ana entegrasyon noktaları:

• Web kancası orders/create olaylarını dinler
• Sipariş detayları baskı sağlayıcısı API'sine gönderilir
• Takip numarası Etsy API aracılığıyla geri döndürülür ve güncellenir
• Müşteri otomatik kargo bildirimi alır

Analiz Kontrol Paneli

Bir satıcı analiz aracı, birden fazla mağazadaki verileri toplar:

• Zorluk: Birden fazla mağazası olan satıcılar birleşik raporlamadan yoksundu
• Çözüm: OAuth tabanlı çoklu mağaza veri toplama
• Sonuç: Satışlar, trafik ve dönüşüm metrikleriyle gerçek zamanlı kontrol paneli

API aracılığıyla toplanan veriler:

• Mağaza istatistikleri (listelemeler, satışlar, gelir)
• Sipariş geçmişi ve trendler
• Listeleme performans metrikleri
• Müşteri inceleme verileri

Sonuç

Etsy API, pazar yeri işlevselliğine kapsamlı erişim sağlar. Anahtar çıkarımlar:

• OAuth 2.0 kimlik doğrulaması, dikkatli belirteç yönetimi ve otomatik yenileme gerektirir
• Hız sınırlama (10 istek/s, 10K/saat) proaktif izleme ve kuyruklama gerektirir
• Web kancaları gerçek zamanlı sipariş ve envanter senkronizasyonunu sağlar
• Üretim güvenilirliği için uygun hata işleme ve yeniden deneme mantığı şarttır
• Apidog, Etsy entegrasyonları için API testini ve ekip işbirliğini kolaylaştırır

SSS Bölümü

Etsy API ne için kullanılır?

Etsy API, geliştiricilerin Etsy pazar yeriyle etkileşim kuran uygulamalar oluşturmasına olanak tanır. Yaygın kullanım durumları arasında birden fazla satış kanalında envanter yönetimi, otomatik sipariş karşılama, analiz kontrol panelleri, listeleme oluşturma araçları ve müşteri ilişkileri yönetimi sistemleri bulunur.

Etsy API anahtarını nasıl alabilirim?

Etsy Geliştirici Portalı'nda bir hesap oluşturun, Uygulamalarınız'a gidin ve Yeni bir uygulama oluştur'a tıklayın. Kayıttan sonra, bir Anahtar Dizini (genel tanımlayıcı) ve Paylaşılan Gizli Anahtar (özel anahtar) alacaksınız. Her ikisini de ortam değişkenleri kullanarak güvenli bir şekilde saklayın.

Etsy API'si ücretsiz mi?

Evet, Etsy API geliştiriciler için ücretsizdir. Ancak, hız limitleri uygulanır: uygulama başına saniyede 10 istek ve saatte 10.000 çağrı. Daha yüksek limitler, belirli kullanım durumları için Etsy'den onay gerektirir.

Etsy API hangi kimlik doğrulamasını kullanır?

Etsy, kimlik doğrulama için OAuth 2.0 kullanır. Kullanıcılar uygulamanızı Etsy'nin yetkilendirme sayfası aracılığıyla yetkilendirir ve uygulamanız bir erişim belirteci (1 saat geçerli) ve yeni erişim belirteçleri almak için bir yenileme belirteci alır.

Etsy API hız limitlerini nasıl yönetirim?

Saniyede 10 isteğin altında kalmak için istek kuyruklamasını uygulayın. Saatlik kullanımı izlemek için x-etsy-quota-remaining başlığını izleyin. HTTP 429 (Çok Fazla İstek) yanıtları alırken üstel geri çekilme kullanın.

Canlı bir mağaza olmadan Etsy API'sini test edebilir miyim?

Evet. Geliştirme modu uygulamaları, entegrasyon testi için test mağazalarına bağlanabilir. Test Etsy hesabı oluşturun ve canlı verileri etkilemeden geliştirme uygulamanızı doğrulamak için kullanın.

Etsy API ile web kancaları nasıl çalışır?

Etsy web kancaları, olaylar meydana geldiğinde (yeni siparişler, listeleme güncellemeleri) HTTPS uç noktanıza POST istekleri gönderir. Uygulama panonuzda web kancalarını yapılandırın, imza doğrulamasını uygulayın ve 5 saniye içinde 200 OK döndürün.

Etsy OAuth belirtecinin süresi dolduğunda ne olur?

Erişim belirteçleri 1 saat sonra sona erer. Süresi dolmadan önce yeni bir erişim belirteci almak için yenileme belirtecini kullanın. API çağrıları sırasında kimlik doğrulama hatalarını önlemek için ara yazılımınızda otomatik belirteç yenilemeyi uygulayın.

API aracılığıyla listeleme görselleri yükleyebilir miyim?

Evet. Görseller, listeleme oluşturulduktan sonra ayrı bir API çağrısında Base64 kodlu dizeler olarak yüklenir. Her görsel 20MB'a kadar olabilir ve JPEG, PNG veya GIF biçiminde olmalıdır.

Etsy API V2'den V3'e nasıl geçiş yaparım?

V3, OAuth 1.0a yerine OAuth 2.0 kullanır ve farklı bir uç nokta yapısına sahiptir. Kimlik doğrulama akışını güncelleyin, uç nokta yollarını /v2/'den /v3/application/'a değiştirin ve V2'nin 2026 sonlarında kullanımdan kaldırılmasından önce kapsamlı bir şekilde test edin.