วิธีใช้ Etsy API ฉบับสมบูรณ์ คู่มือเชื่อมต่อ (2026)

สรุปเนื้อหา

Etsy API ช่วยให้นักพัฒนาสามารถสร้างแอปพลิเคชันที่โต้ตอบกับตลาดกลางของ Etsy ได้ โดยใช้การรับรองความถูกต้องด้วย OAuth 2.0, มีเอนด์พอยต์ RESTful สำหรับร้านค้า, รายการสินค้า, คำสั่งซื้อ และการจัดการคลังสินค้า พร้อมจำกัดอัตราการเรียกใช้ที่ 10 ครั้งต่อวินาทีต่อแอปพลิเคชัน คู่มือนี้ครอบคลุมการตั้งค่าการรับรองความถูกต้อง, เอนด์พอยต์หลัก, การรวม Webhook และกลยุทธ์การปรับใช้ในสภาพแวดล้อมจริง

บทนำ

Etsy มียอดขายสินค้ารวมต่อปีมากกว่า 1.3 หมื่นล้านดอลลาร์สหรัฐในกว่า 230 ประเทศ สำหรับนักพัฒนาที่สร้างเครื่องมืออีคอมเมิร์ซ, ระบบการจัดการสินค้าคงคลัง หรือแพลตฟอร์มการวิเคราะห์ การผสานรวม Etsy API จึงเป็นสิ่งสำคัญอย่างยิ่ง

นี่คือความเป็นจริง: ผู้ขายที่จัดการช่องทางการขายหลายช่องทางสูญเสียเวลา 15-20 ชั่วโมงต่อสัปดาห์ในการป้อนข้อมูลด้วยตนเอง การผสานรวม Etsy API ที่ดีจะช่วยทำให้การซิงโครไนซ์รายการสินค้า, การประมวลผลคำสั่งซื้อ และการอัปเดตสินค้าคงคลังข้ามแพลตฟอร์มเป็นไปโดยอัตโนมัติ

คู่มือนี้จะนำคุณเข้าสู่กระบวนการผสานรวม Etsy API ทั้งหมด คุณจะได้เรียนรู้การรับรองความถูกต้องด้วย OAuth 2.0, การจัดการร้านค้าและรายการสินค้า, การประมวลผลคำสั่งซื้อ, การจัดการ Webhook และการแก้ไขปัญหาข้อผิดพลาด เมื่อจบคู่มือนี้ คุณจะมีการผสานรวม Etsy ที่พร้อมใช้งานจริง

Etsy API คืออะไร?

Etsy มี RESTful API สำหรับการเข้าถึงข้อมูลตลาดกลางและการจัดการการดำเนินการของผู้ขาย API จัดการสิ่งเหล่านี้:

• การเรียกข้อมูลร้านค้าและโปรไฟล์
• การสร้าง, อัปเดต และการจัดการรายการสินค้า
• การประมวลผลคำสั่งซื้อและการติดตามการจัดส่ง
• การเข้าถึงข้อมูลลูกค้าและการทำธุรกรรม
• โปรไฟล์การจัดส่งและการคำนวณภาษี
• การจัดการการอัปโหลดรูปภาพและสื่อ

คุณสมบัติหลัก

ภาพรวมสถาปัตยกรรม API

Etsy ใช้โครงสร้าง REST API ที่มีการกำหนดเวอร์ชัน:

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

เวอร์ชัน 3 (v3) เป็นมาตรฐานปัจจุบัน ซึ่งนำเสนอการรองรับ OAuth 2.0 ที่ดีขึ้นและโครงสร้างเอนด์พอยต์ที่เรียบง่ายกว่าเมื่อเทียบกับ v2

เปรียบเทียบเวอร์ชัน API

โปรดย้ายการผสานรวม V2 ใดๆ ไปยัง V3 ทันที Etsy ประกาศการเลิกใช้ V2 โดยมีกำหนดการเลิกใช้งานถาวรในช่วงปลายปี 2026

เริ่มต้นใช้งาน: การตั้งค่าการรับรองความถูกต้อง

ขั้นตอนที่ 1: สร้างบัญชีนักพัฒนา Etsy ของคุณ

ก่อนเข้าถึง API คุณต้องมีบัญชีนักพัฒนา:

1. ไปที่ Etsy Developer Portal
2. ลงชื่อเข้าใช้ด้วยบัญชี Etsy ของคุณ (หรือสร้างใหม่)
3. ไปที่ Your Apps ในแดชบอร์ดนักพัฒนา
4. คลิก Create a new app

ขั้นตอนที่ 2: ลงทะเบียนแอปพลิเคชันของคุณ

กรอกแบบฟอร์มการลงทะเบียนแอปพลิเคชัน:

• App Name: ชื่อที่ชัดเจนและสื่อความหมาย (ผู้ใช้จะเห็นระหว่าง OAuth)
• App Description: อธิบายว่าแอปของคุณทำอะไรและใครใช้บ้าง
• Redirect URI: ที่อยู่ซึ่ง Etsy จะส่งผู้ใช้กลับมาหลังจากการรับรองความถูกต้อง (ต้องใช้ HTTPS)
• Production/Development: เริ่มต้นด้วยโหมด development สำหรับการทดสอบ

หลังจากการส่ง คุณจะได้รับ:

• Key String: ตัวระบุ API สาธารณะของคุณ
• Shared Secret: คีย์ลับ API ส่วนตัวของคุณ (ห้ามเปิดเผยเด็ดขาด)

ข้อควรระวังด้านความปลอดภัย: จัดเก็บข้อมูลรับรองในตัวแปรสภาพแวดล้อม (environment variables) อย่าเก็บไว้ในโค้ด:

# .env file
ETSY_KEY_STRING="your_key_string_here"
ETSY_SHARED_SECRET="your_shared_secret_here"
ETSY_ACCESS_TOKEN="generated_via_oauth"
ETSY_REFRESH_TOKEN="generated_via_oauth"

ขั้นตอนที่ 3: ทำความเข้าใจโฟลว์ OAuth 2.0

Etsy ใช้ OAuth 2.0 สำหรับการรับรองความถูกต้อง นี่คือโฟลว์ทั้งหมด:

1. ผู้ใช้คลิก "Connect with Etsy" ในแอปของคุณ
2. แอปของคุณจะเปลี่ยนเส้นทางไปยัง URL การอนุญาตของ Etsy
3. ผู้ใช้ลงชื่อเข้าใช้และให้สิทธิ์
4. Etsy เปลี่ยนเส้นทางกลับมาพร้อมรหัสการอนุญาต
5. แอปของคุณแลกเปลี่ยนรหัสเพื่อรับโทเค็นการเข้าถึง
6. แอปของคุณใช้โทเค็นการเข้าถึงสำหรับการเรียก API
7. รีเฟรชโทเค็นเมื่อโทเค็นการเข้าถึงหมดอายุ (1 ชั่วโมง)

ขั้นตอนที่ 4: ใช้การอนุญาต OAuth

สร้าง URL การอนุญาต:

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, // Random string for CSRF protection
    response_type: 'code'
  });

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

// Usage
const authUrl = generateAuthUrl(
  process.env.ETSY_KEY_STRING,
  'https://your-app.com/callback',
  crypto.randomBytes(16).toString('hex')
);

console.log(`Redirect user to: ${authUrl}`);

ขอบเขตที่จำเป็น (Required Scopes)

ขอเฉพาะสิทธิ์ที่แอปของคุณต้องการเท่านั้น:

ขั้นตอนที่ 5: แลกเปลี่ยนรหัสเพื่อรับโทเค็นการเข้าถึง

จัดการการเรียกกลับ OAuth และแลกเปลี่ยนรหัสการอนุญาต:

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();

  // Store these securely in your database
  return {
    access_token: data.access_token,
    refresh_token: data.refresh_token,
    expires_in: data.expires_in, // Typically 3600 seconds (1 hour)
    user_id: data.user_id,
    scope: data.scope
  };
};

// Handle callback route
app.get('/callback', async (req, res) => {
  const { code, state } = req.query;

  // Verify state matches what you sent (CSRF protection)
  if (state !== req.session.oauthState) {
    return res.status(400).send('Invalid state parameter');
  }

  try {
    const tokens = await exchangeCodeForToken(code, 'https://your-app.com/callback');

    // Store tokens in database associated with user
    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('/dashboard');
  } catch (error) {
    console.error('Token exchange failed:', error);
    res.status(500).send('Authentication failed');
  }
});

ขั้นตอนที่ 6: ใช้การรีเฟรชโทเค็น

โทเค็นการเข้าถึงจะหมดอายุหลังจาก 1 ชั่วโมง โปรดใช้การรีเฟรชอัตโนมัติ:

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();

  // Update stored tokens
  return {
    access_token: data.access_token,
    refresh_token: data.refresh_token, // Always save the new refresh token
    expires_in: data.expires_in
  };
};

// Middleware to ensure valid token before API calls
const ensureValidToken = async (userId) => {
  const user = await db.users.findById(userId);

  // Check if token expires within 5 minutes
  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;
};

ขั้นตอนที่ 7: ทำการเรียกใช้ API ที่มีการรับรองความถูกต้อง

รวมโทเค็นการเข้าถึงในการร้องขอทุกครั้ง:

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 Error: ${error.message}`);
  }

  return response.json();
};

เอนด์พอยต์การจัดการร้านค้า

การดึงข้อมูลร้านค้า

ดึงรายละเอียดร้านค้า, นโยบาย และการตั้งค่า:

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

  return response;
};

// Usage
const shop = await getShopInfo(12345678);
console.log(`Shop: ${shop.title}`);
console.log(`Currency: ${shop.currency_code}`);
console.log(`Listings count: ${shop.num_listings_active}`);

การตอบกลับข้อมูลร้านค้าที่คาดหวัง

{
  "shop_id": 12345678,
  "shop_name": "MyHandmadeShop",
  "title": "Handmade Jewelry & Accessories",
  "announcement": "Welcome! Free shipping on orders over $50",
  "currency_code": "USD",
  "is_vacation": false,
  "vacation_message": null,
  "sale_message": "Thank you for supporting small businesses!",
  "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/MyHandmadeShop",
  "image_url_760x100": "https://i.etsystatic.com/.../banner_760x100.jpg"
}

การดึงส่วนร้านค้า (Shop Sections)

จัดระเบียบรายการสินค้าตามส่วนต่างๆ:

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

  return response;
};

// Example response
{
  "count": 5,
  "results": [
    {
      "shop_section_id": 12345,
      "title": "Necklaces",
      "rank": 1,
      "num_listings": 23
    },
    {
      "shop_section_id": 12346,
      "title": "Earrings",
      "rank": 2,
      "num_listings": 45
    }
  ]
}

การจัดการรายการสินค้า

การสร้างรายการสินค้าใหม่

สร้างรายการสินค้าพร้อมรูปภาพและตัวเลือกสินค้า (variations):

const createListing = async (shopId, listingData) => {
  const payload = {
    title: listingData.title,
    description: listingData.description,
    price: listingData.price.toString(), // Must be string
    quantity: listingData.quantity,
    sku: listingData.sku || [],
    tags: listingData.tags.slice(0, 13), // Max 13 tags
    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, etc.
    is_supply: listingData.isSupply, // true for craft supplies
    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, // men, women, unisex, etc.
    occasion: listingData.occasion || null, // birthday, wedding, etc.
    style: listingData.style || [] // Max 2 styles
  };

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

  return response;
};

// Usage example
const listing = await createListing(12345678, {
  title: 'Sterling Silver Moon Phase Necklace',
  description: 'Handcrafted sterling silver necklace featuring moon phases...',
  price: 89.99,
  quantity: 15,
  sku: ['MOON-NECKLACE-001'],
  tags: ['moon necklace', 'sterling silver', 'moon phase', 'celestial jewelry'],
  categoryId: 10623, // Jewelry > Necklaces
  sectionId: 12345,
  state: 'active',
  whoMade: 'i_did',
  whenMade: 'made_to_order',
  isSupply: false,
  weight: 25,
  weightUnit: 'g'
});

การอัปโหลดรูปภาพรายการสินค้า

รูปภาพจะถูกอัปโหลดแยกต่างหากหลังจากการ สร้างรายการสินค้า:

const uploadListingImage = async (listingId, imagePath, imagePosition = 1) => {
  // Read image file as base64
  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: 'Handcrafted sterling silver moon phase necklace' // For accessibility
  };

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

  return response;
};

// Upload multiple images
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;
};

การอัปเดตสต็อกสินค้า

อัปเดตจำนวนสินค้าคงคลังสำหรับรายการสินค้าที่มีอยู่:

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;
};

// Usage
await updateListingInventory(12345678, 987654321, {
  products: [
    { sku: 'MOON-NECKLACE-001', quantity: 10 },
    { sku: 'MOON-NECKLACE-002', quantity: 5 }
  ],
  isOverSelling: false
});

การดึงรายการสินค้า

ดึงรายการสินค้าทั้งหมดหรือกรองตามสถานะ:

const getListings = async (shopId, options = {}) => {
  const params = new URLSearchParams({
    limit: options.limit || 25, // Max 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;
};

// Get a single listing
const getListing = async (listingId) => {
  const response = await makeEtsyRequest(`/listings/${listingId}`, {
    method: 'GET'
  });

  return response;
};

การลบรายการสินค้า

ลบรายการสินค้าออกจากร้านค้าของคุณ:

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

  return response;
};

การจัดการคำสั่งซื้อ

การดึงคำสั่งซื้อ

ดึงคำสั่งซื้อพร้อมตัวเลือกการกรอง:

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;
};

// Get a single order
const getOrder = async (shopId, orderId) => {
  const response = await makeEtsyRequest(`/shops/${shopId}/orders/${orderId}`, {
    method: 'GET'
  });

  return response;
};

โครงสร้างการตอบกลับของคำสั่งซื้อ

{
  "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": "Jane Doe",
  "email": "jane.doe@email.com",
  "buyer_phone_number": "+1-555-0123",
  "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": "Jane Doe",
    "address_line1": "123 Main Street",
    "address_line2": "Apt 4B",
    "city": "New York",
    "state": "NY",
    "zip": "10001",
    "country": "US",
    "phone": "+1-555-0123"
  },
  "listings": [
    {
      "listing_id": 987654321,
      "title": "Sterling Silver Moon Phase Necklace",
      "sku": ["MOON-NECKLACE-001"],
      "quantity": 1,
      "price": "89.99"
    }
  ]
}

การอัปเดตสถานะคำสั่งซื้อ

ทำเครื่องหมายคำสั่งซื้อว่าเสร็จสมบูรณ์และเพิ่มการติดตาม:

const updateOrderStatus = async (shopId, orderId, trackingData) => {
  const payload = {
    carrier_id: trackingData.carrierId, // usps, fedex, ups, etc.
    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;
};

// Usage
await updateOrderStatus(12345678, 1234567890, {
  carrierId: 'usps',
  trackingCode: '9400111899223456789012',
  notifyBuyer: true
});

รหัสผู้ให้บริการขนส่งที่พบบ่อย

การจำกัดอัตราและโควต้า

การทำความเข้าใจการจำกัดอัตรา

Etsy บังคับใช้การจำกัดอัตราเพื่อปกป้องความเสถียรของ API:

• ขีดจำกัดมาตรฐาน: 10 คำขอต่อวินาทีต่อแอป
• ค่าเผื่อสำหรับการใช้งานชั่วคราว (Burst Allowance): สูงสุด 50 คำขอในหนึ่งวินาที (การใช้งานชั่วคราวระยะสั้น)
• ระบบโควต้า: 10,000 การเรียกต่อชั่วโมงต่อแอป (รีเซ็ตทุกชั่วโมง)

การเกินขีดจำกัดจะส่งผลให้เกิดการตอบกลับ HTTP 429 (Too Many Requests)

การจัดการการจำกัดอัตรา

ใช้ exponential backoff สำหรับการลองใหม่:

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

      // Check rate limit headers
      const remaining = response.headers.get('x-etsy-quota-remaining');
      const resetTime = response.headers.get('x-etsy-quota-reset');

      if (remaining < 100) {
        console.warn(`Low quota remaining: ${remaining}, resets at ${resetTime}`);
      }

      return response;
    } catch (error) {
      if (error.message.includes('429') && attempt < maxRetries) {
        // Exponential backoff: 1s, 2s, 4s
        const delay = Math.pow(2, attempt) * 1000;
        console.log(`Rate limited. Retrying in ${delay}ms...`);
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        throw error;
      }
    }
  }
};

ส่วนหัวการจำกัดอัตรา (Rate Limit Headers)

Etsy รวมส่วนหัวเหล่านี้ในการตอบกลับทุกครั้ง:

ควรบันทึกส่วนหัวเหล่านี้เสมอสำหรับการตรวจสอบและแก้ไขข้อบกพร่อง

การผสานรวม Webhook

การกำหนดค่า Webhook

Etsy รองรับ webhooks สำหรับการแจ้งเตือนเหตุการณ์แบบเรียลไทม์:

1. ไปที่ Your Apps ในแดชบอร์ดนักพัฒนา
2. เลือกแอปของคุณ
3. คลิก Add Webhook
4. ป้อน URL เอนด์พอยต์ HTTPS ของคุณ
5. เลือกเหตุการณ์ที่จะสมัครรับข้อมูล

เหตุการณ์ Webhook ที่ใช้งานได้

การสร้างตัวจัดการ Webhook

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;

  // Verify webhook signature
  const isValid = verifyWebhookSignature(payload, signature, process.env.ETSY_WEBHOOK_SECRET);

  if (!isValid) {
    console.error('Invalid webhook signature');
    return res.status(401).send('Unauthorized');
  }

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

  // Route to appropriate handler
  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('Unhandled event type:', event.type);
  }

  // Acknowledge receipt within 5 seconds
  res.status(200).send('OK');
});

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')
  );
}

แนวทางปฏิบัติที่ดีที่สุดสำหรับ Webhook

1. ตรวจสอบลายเซ็น - ป้องกัน webhooks ที่ถูกปลอมแปลง
2. ตอบกลับ 200 OK อย่างรวดเร็ว - Etsy จะลองใหม่หากไม่ได้รับ 200 OK ภายใน 5 วินาที
3. ประมวลผลแบบอะซิงโครนัส - จัดคิวเหตุการณ์สำหรับการประมวลผลเบื้องหลัง
4. ใช้ idempotency - จัดการการส่ง webhook ที่ซ้ำกัน
5. บันทึกเหตุการณ์ทั้งหมด - แก้ไขปัญหาด้วยบันทึกการตรวจสอบที่มีการประทับเวลา

การแก้ไขปัญหาที่พบบ่อย

ปัญหา: การแลกเปลี่ยนโทเค็น OAuth ล้มเหลว

อาการ: ได้รับข้อผิดพลาด 401 หรือ 403 ระหว่างการรับรองความถูกต้อง

การวินิจฉัย:

// Check error response
const error = await response.json();
console.error('OAuth error:', error);

วิธีแก้ไข:

1. ตรวจสอบว่า Redirect URI ตรงกันทุกประการ (รวมถึง https:// และ trailing slash)
2. ยืนยันว่า client_id และ client_secret ถูกต้อง
3. ตรวจสอบให้แน่ใจว่ารหัสการอนุญาตยังไม่หมดอายุ (รหัสจะหมดอายุหลังจากใช้งาน 1 ครั้งหรือ 5 นาที)
4. ตรวจสอบว่าแอปอยู่ในโหมด production (แอปในโหมด development สามารถเข้าถึงได้เฉพาะบัญชีทดสอบเท่านั้น)

ปัญหา: เกินขีดจำกัดอัตราการใช้งาน

อาการ: ได้รับการตอบกลับ HTTP 429

วิธีแก้ไข:

1. ใช้การจัดคิวคำขอพร้อมการจำกัดอัตรา
2. ใช้ exponential backoff สำหรับการลองใหม่
3. รวมคำขอเข้าด้วยกันเท่าที่จะทำได้ (เช่น ดึงรายการสินค้าหลายรายการในการเรียกครั้งเดียว)
4. ตรวจสอบส่วนหัวโควต้าและชะลอการส่งคำขอเชิงรุก

// Simple rate limiter
class RateLimiter {
  constructor(requestsPerSecond = 9) { // Stay under 10/s limit
    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;
  }
}

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

ปัญหา: การสร้างรายการสินค้าล้มเหลวเนื่องจากข้อผิดพลาดในการตรวจสอบ

อาการ: 400 Bad Request พร้อมข้อความแสดงข้อผิดพลาดในการตรวจสอบ

สาเหตุทั่วไป:

1. category_id ไม่ถูกต้อง: ใช้ API หมวดหมู่ของ Etsy เพื่อรับ ID ที่ถูกต้อง
2. รูปแบบราคา: ต้องเป็นสตริง ไม่ใช่ตัวเลข
3. ขีดจำกัดแท็ก: สูงสุด 13 แท็กต่อรายการสินค้า
4. ฟิลด์ที่จำเป็นขาดหายไป: title, description, price, quantity, who_made, when_made

วิธีแก้ไข:

// Validate before sending
const validateListing = (data) => {
  const errors = [];

  if (!data.title || data.title.length < 5) {
    errors.push('Title must be at least 5 characters');
  }

  if (typeof data.price !== 'string') {
    errors.push('Price must be a string');
  }

  if (data.tags && data.tags.length > 13) {
    errors.push('Maximum 13 tags allowed');
  }

  if (!['i_did', 'someone_else', 'collective'].includes(data.whoMade)) {
    errors.push('Invalid who_made value');
  }

  return errors;
};

ปัญหา: Webhooks ไม่มาถึง

อาการ: คำสั่งซื้อได้รับการประมวลผล แต่เอนด์พอยต์ webhook ไม่ได้รับอะไรเลย

การวินิจฉัย:

1. ตรวจสอบบันทึกการส่ง webhook ในแดชบอร์ดนักพัฒนา
2. ตรวจสอบว่าเอนด์พอยต์ส่งคืน 200 OK ภายใน 5 วินาที
3. ทดสอบเอนด์พอยต์ด้วยตนเองโดยใช้ curl

วิธีแก้ไข:

1. ตรวจสอบให้แน่ใจว่าใช้ HTTPS พร้อมใบรับรอง SSL ที่ถูกต้อง
2. อนุญาต IP ของ Etsy webhook ในไฟร์วอลล์
3. ตรวจสอบตรรกะการตรวจสอบลายเซ็น
4. ใช้เครื่องมือทดสอบ webhook ระหว่างการพัฒนา

ปัญหา: รูปภาพอัปโหลดล้มเหลว

อาการ: รายการสินค้าสร้างขึ้น แต่รูปภาพส่งคืนข้อผิดพลาด

วิธีแก้ไข:

1. ตรวจสอบว่ารูปภาพเป็นรูปแบบที่ถูกต้อง (JPEG, PNG, GIF)
2. ตรวจสอบขนาดไฟล์ (สูงสุด 20MB ต่อรูปภาพ)
3. ตรวจสอบให้แน่ใจว่าการเข้ารหัส base64 ถูกต้อง
4. ยืนยันว่ารายการสินค้ามีอยู่ก่อนอัปโหลดรูปภาพ
5. อัปโหลดรูปภาพตามลำดับ ไม่ใช่แบบขนาน

รายการตรวจสอบการปรับใช้ในสภาพแวดล้อมจริง

ก่อนเปิดใช้งานจริง:

• [ ] สลับจากโหมด development เป็นโหมด production ของแอป
• [ ] อัปเดต Redirect URI ทั้งหมดเป็น URL ของ production
• [ ] ใช้การจัดเก็บโทเค็นอย่างปลอดภัย (ฐานข้อมูลที่เข้ารหัส)
• [ ] เพิ่มตรรกะการรีเฟรชโทเค็นอัตโนมัติ
• [ ] ตั้งค่าการจำกัดอัตราและการจัดคิวคำขอ
• [ ] กำหนดค่าเอนด์พอยต์ webhook ด้วย HTTPS
• [ ] ใช้การจัดการข้อผิดพลาดที่ครอบคลุม
• [ ] เพิ่มการบันทึกสำหรับการเรียกใช้ API ทั้งหมด
• [ ] ตั้งค่าการตรวจสอบสำหรับการใช้งานโควต้า
• [ ] สร้างคู่มือการดำเนินงานสำหรับปัญหาทั่วไป
• [ ] ทดสอบกับบัญชีร้านค้าหลายบัญชี
• [ ] จัดทำเอกสารโฟลว์ OAuth สำหรับการเริ่มต้นใช้งานของผู้ใช้

การตรวจสอบและการแจ้งเตือน

ติดตามเมตริกเหล่านี้:

// Example metrics to track
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
  }
};

// Alert on high failure rate
const failureRate = metrics.apiCalls.failed / metrics.apiCalls.total;

if (failureRate > 0.05) { // More than 5% failure rate
  sendAlert('Etsy API failure rate above 5%');
}

// Alert on low quota
if (metrics.quotaUsage.current < 500) {
  sendAlert('Etsy API quota below 500 calls remaining');
}

กรณีการใช้งานจริง

การซิงค์สต็อกสินค้าหลายช่องทาง

ผู้ขายสินค้าตกแต่งบ้านใช้ Etsy API เพื่อซิงโครไนซ์สต็อกสินค้าข้าม Etsy, Shopify และ Amazon:

• ความท้าทาย: การอัปเดตสต็อกด้วยตนเองนำไปสู่การขายเกินจำนวน (overselling)
• วิธีแก้ไข: ระบบสต็อกกลางพร้อม Etsy API webhooks
• ผลลัพธ์: ไม่มีเหตุการณ์ขายเกินจำนวน ลดเวลาได้ 12 ชั่วโมงต่อสัปดาห์

ขั้นตอนการใช้งาน:

1. Webhook ของ Etsy ทริกเกอร์เมื่อมีการสร้างคำสั่งซื้อ
2. ระบบกลางลดจำนวนสต็อก
3. การเรียก API อัปเดตจำนวนสินค้าใน Shopify และ Amazon
4. การยืนยันถูกบันทึกลงในฐานข้อมูล

การจัดการคำสั่งซื้ออัตโนมัติ

ธุรกิจ Print-on-Demand (POD) ทำให้กระบวนการจัดการคำสั่งซื้อเป็นอัตโนมัติ:

• ความท้าทาย: คำสั่งซื้อมากกว่า 50 รายการต่อวันต้องมีการป้อนข้อมูลด้วยตนเอง
• วิธีแก้ไข: การผสานรวม Etsy API กับผู้ให้บริการจัดส่ง
• ผลลัพธ์: คำสั่งซื้อถูกส่งไปยังการผลิตโดยอัตโนมัติภายใน 5 นาที

จุดผสานรวมที่สำคัญ:

• Webhook ดักจับเหตุการณ์ orders/create
• รายละเอียดคำสั่งซื้อถูกส่งไปยัง API ของผู้ให้บริการพิมพ์
• หมายเลขติดตามถูกส่งกลับและอัปเดตผ่าน Etsy API
• ลูกค้าได้รับการแจ้งเตือนการจัดส่งอัตโนมัติ

แดชบอร์ดวิเคราะห์

เครื่องมือวิเคราะห์ผู้ขายรวบรวมข้อมูลจากร้านค้าหลายแห่ง:

• ความท้าทาย: ผู้ขายที่มีร้านค้าหลายแห่งขาดการรายงานที่เป็นหนึ่งเดียว
• วิธีแก้ไข: การรวมข้อมูลจากหลายร้านค้าโดยใช้ OAuth
• ผลลัพธ์: แดชบอร์ดแบบเรียลไทม์พร้อมเมตริกการขาย, การเข้าชม และอัตราการแปลง

ข้อมูลที่รวบรวมผ่าน API:

• สถิติร้านค้า (รายการสินค้า, ยอดขาย, รายได้)
• ประวัติและแนวโน้มคำสั่งซื้อ
• เมตริกประสิทธิภาพรายการสินค้า
• ข้อมูลรีวิวลูกค้า

บทสรุป

Etsy API ให้การเข้าถึงฟังก์ชันการทำงานของตลาดกลางอย่างครอบคลุม ประเด็นสำคัญ:

• การรับรองความถูกต้องด้วย OAuth 2.0 ต้องมีการจัดการโทเค็นและการรีเฟรชอัตโนมัติอย่างระมัดระวัง
• การจำกัดอัตรา (10 คำขอ/วินาที, 10K/ชั่วโมง) ต้องมีการตรวจสอบเชิงรุกและการจัดคิว
• Webhooks ช่วยให้การซิงโครไนซ์คำสั่งซื้อและสต็อกสินค้าแบบเรียลไทม์
• การจัดการข้อผิดพลาดและตรรกะการลองใหม่ที่เหมาะสมเป็นสิ่งสำคัญสำหรับความน่าเชื่อถือในการใช้งานจริง
• Apidog ช่วยให้การทดสอบ API และการทำงานร่วมกันเป็นทีมสำหรับการผสานรวม Etsy ง่ายขึ้น

ส่วนคำถามที่พบบ่อย (FAQ)

Etsy API ใช้สำหรับอะไร?

Etsy API ช่วยให้นักพัฒนาสามารถสร้างแอปพลิเคชันที่โต้ตอบกับตลาดกลางของ Etsy ได้ กรณีการใช้งานทั่วไปได้แก่ การจัดการสต็อกสินค้าข้ามช่องทางการขายหลายช่องทาง, การจัดการคำสั่งซื้ออัตโนมัติ, แดชบอร์ดวิเคราะห์, เครื่องมือสร้างรายการสินค้า และระบบการจัดการลูกค้าสัมพันธ์

ฉันจะรับ Etsy API key ได้อย่างไร?

สร้างบัญชีที่ Etsy Developer Portal ไปที่ Your Apps และคลิก Create a new app หลังจากลงทะเบียน คุณจะได้รับ Key String (ตัวระบุสาธารณะ) และ Shared Secret (คีย์ส่วนตัว) โปรดจัดเก็บทั้งสองอย่างให้ปลอดภัยโดยใช้ตัวแปรสภาพแวดล้อม

Etsy API ใช้งานฟรีหรือไม่?

ใช่ Etsy API ใช้งานฟรีสำหรับนักพัฒนา อย่างไรก็ตาม มีการจำกัดอัตรา: 10 คำขอต่อวินาที และ 10,000 การเรียกต่อชั่วโมงต่อแอปพลิเคชัน การใช้งานเกินขีดจำกัดต้องได้รับการอนุมัติจาก Etsy สำหรับกรณีการใช้งานเฉพาะ

Etsy API ใช้การรับรองความถูกต้องแบบใด?

Etsy ใช้ OAuth 2.0 สำหรับการรับรองความถูกต้อง ผู้ใช้จะอนุญาตแอปของคุณผ่านหน้าการอนุญาตของ Etsy และแอปของคุณจะได้รับโทเค็นการเข้าถึง (มีอายุ 1 ชั่วโมง) และโทเค็นรีเฟรช (สำหรับขอโทเค็นการเข้าถึงใหม่)

ฉันจะจัดการการจำกัดอัตราของ Etsy API ได้อย่างไร?

ใช้การจัดคิวคำขอเพื่อให้ยังอยู่ภายใต้ 10 คำขอต่อวินาที ตรวจสอบส่วนหัว x-etsy-quota-remaining เพื่อติดตามการใช้งานรายชั่วโมง ใช้ exponential backoff เมื่อได้รับข้อความ HTTP 429 (Too Many Requests)

ฉันสามารถทดสอบ Etsy API โดยไม่มีร้านค้าจริงได้หรือไม่?

ได้ แอปในโหมด development สามารถเชื่อมต่อกับร้านค้าทดสอบเพื่อการทดสอบการผสานรวม สร้างบัญชี Etsy สำหรับทดสอบและใช้เพื่อรับรองความถูกต้องของแอปในโหมด development ของคุณโดยไม่ส่งผลกระทบต่อข้อมูลจริง

Webhooks ทำงานอย่างไรกับ Etsy API?

Etsy webhooks จะส่งคำขอ POST ไปยังเอนด์พอยต์ HTTPS ของคุณเมื่อมีเหตุการณ์เกิดขึ้น (คำสั่งซื้อใหม่, การอัปเดตรายการสินค้า) กำหนดค่า webhooks ในแดชบอร์ดแอปของคุณ, ใช้การตรวจสอบลายเซ็น และส่งคืน 200 OK ภายใน 5 วินาที

จะเกิดอะไรขึ้นเมื่อโทเค็น OAuth ของ Etsy หมดอายุ?

โทเค็นการเข้าถึงจะหมดอายุหลังจาก 1 ชั่วโมง ใช้โทเค็นรีเฟรชเพื่อขอโทเค็นการเข้าถึงใหม่ก่อนหมดอายุ ใช้การรีเฟรชโทเค็นอัตโนมัติใน middleware ของคุณเพื่อป้องกันความล้มเหลวในการรับรองความถูกต้องระหว่างการเรียกใช้ API

ฉันสามารถอัปโหลดรูปภาพรายการสินค้าผ่าน API ได้หรือไม่?

ได้ รูปภาพจะถูกอัปโหลดเป็นสตริงที่เข้ารหัสแบบ base64 ในการเรียกใช้ API แยกต่างหากหลังจากสร้างรายการสินค้า รูปภาพแต่ละภาพมีขนาดสูงสุด 20MB และต้องเป็นรูปแบบ JPEG, PNG หรือ GIF

ฉันจะย้ายจาก Etsy API V2 ไปยัง V3 ได้อย่างไร?

V3 ใช้ OAuth 2.0 แทน OAuth 1.0a และมีโครงสร้างเอนด์พอยต์ที่แตกต่างกัน อัปเดตโฟลว์การรับรองความถูกต้อง, แก้ไขพาธเอนด์พอยต์จาก /v2/ เป็น /v3/application/ และทดสอบอย่างละเอียดก่อนที่ V2 จะเลิกใช้งานถาวรในช่วงปลายปี 2026