Hướng Dẫn Sử Dụng eBay APIs Hiệu Quả

TL;DR

API của eBay cho phép bạn quản lý kho hàng, danh sách sản phẩm, đơn hàng và thanh toán trên thị trường lớn nhất thế giới. Bạn xác thực bằng OAuth 2.0, gọi các điểm cuối (endpoints) api.ebay.com/sell và xử lý giới hạn tốc độ một cách cẩn thận. Để thử nghiệm, hãy sử dụng Apidog để xác thực dữ liệu gửi đi (payloads) của danh sách sản phẩm, kiểm tra quy trình xử lý đơn hàng và đảm bảo tích hợp của bạn xử lý giới hạn API một cách linh hoạt.

Giới thiệu

eBay kết nối người mua và người bán trên toàn cầu. API cho phép người bán tự động hóa việc quản lý kho hàng, tạo danh sách sản phẩm hàng loạt, xử lý đơn hàng, xử lý vận chuyển và quản lý trả hàng. Dù bạn là người bán nhỏ hay một doanh nghiệp lớn, API đều có khả năng mở rộng.

Các lĩnh vực API chính:

Inventory API - Quản lý kho hàng sản phẩm
Listing API - Tạo và quản lý danh sách sản phẩm
Order API - Xử lý đơn hàng và vận chuyển
Fulfillment API - Xử lý vận chuyển và theo dõi
Analytics API - Kéo báo cáo bán hàng

💡

Nếu bạn đang xây dựng các tích hợp với eBay, Apidog giúp bạn kiểm tra việc tạo danh sách sản phẩm, xác thực phản hồi đơn hàng và đảm bảo tích hợp của bạn xử lý giới hạn tốc độ và lỗi một cách chính xác.

Tải ứng dụng

Thử nghiệm API của eBay với Apidog - miễn phí

Sau khi đọc xong hướng dẫn này, bạn sẽ có thể:

Xác thực với eBay OAuth 2.0
Tạo và quản lý kho hàng
Đăng danh sách sản phẩm
Xử lý đơn hàng và vận chuyển
Xử lý trả hàng và hoàn tiền
Kiểm tra với Apidog

Xác thực với OAuth 2.0

eBay sử dụng OAuth 2.0 để xác thực API. Bạn sẽ cần tạo một ứng dụng trong Chương trình Nhà phát triển eBay.

Tạo một ứng dụng

Truy cập developers.ebay.com
Đăng ký tài khoản nhà phát triển
Tạo một ứng dụng trong Developer Console
Lấy App ID (client ID) và Cert ID (client secret) của bạn

Luồng OAuth

Bước 1: Ủy quyền người dùng

https://auth.ebay.com/oauth2/authorize?
  client_id=YOUR_APP_ID&
  response_type=code&
  redirect_uri=YOUR_SIGNIN_REDIRECT_URI&
  scope=https://api.ebay.com/oauth/api_scope/sell.inventory

Bước 2: Lấy mã ủy quyền

Người dùng ủy quyền, bạn nhận được mã tại URI chuyển hướng của mình.

Bước 3: Trao đổi để lấy token

const response = await fetch('https://api.ebay.com/identity/v1/oauth2/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Authorization': 'Basic ' + Buffer.from(APP_ID + ':' + CERT_ID).toString('base64')
  },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    code: AUTHORIZATION_CODE,
    redirect_uri: 'YOUR_SIGNIN_REDIRECT_URI'
  })
})

const { access_token, refresh_token, expires_in } = await response.json()

Các quyền (scopes) yêu cầu

https://api.ebay.com/oauth/api_scope/sell.inventory - Quản lý kho hàng
https://api.ebay.com/oauth/api_scope/sell.listings - Danh sách sản phẩm
https://api.ebay.com/oauth/api_scope/sell.orders - Đơn hàng
https://api.ebay.com/oauth/api_scope/sell.fulfillment - Thực hiện đơn hàng
https://api.ebay.com/oauth/api_scope/sell.account - Quản lý tài khoản

Quản lý kho hàng

Kho hàng đại diện cho các sản phẩm bạn bán.

Tạo vị trí kho hàng

curl -X POST "https://api.ebay.com/sell/inventory/v1/location_inventory_location" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "locationId": "WAREHOUSE_1",
    "name": "Main Warehouse",
    "address": {
      "addressLine1": "123 Main St",
      "city": "San Jose",
      "stateOrProvince": "CA",
      "postalCode": "95101",
      "countryCode": "US"
    }
  }'

Tạo một mặt hàng trong kho

curl -X POST "https://api.ebay.com/sell/inventory/v1/inventory_item" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product": {
      "title": "Vintage Leather Messenger Bag",
      "description": "Genuine leather messenger bag, perfect for work or school.",
      "aspects": {
        "Brand": ["Vintage"],
        "Material": ["Leather"],
        "Color": ["Brown"]
      },
      "imageUrls": [
        "https://example.com/images/bag1.jpg",
        "https://example.com/images/bag2.jpg"
      ]
    },
    "condition": "USED_GOOD",
    "conditionNotes": "Minor wear on corners",
    "availability": {
      "shipToLocationAvailability": {
        "quantity": 25
      }
    }
  }'

Cập nhật kho hàng

curl -X PUT "https://api.ebay.com/sell/inventory/v1/inventory_item/SKU123" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "availability": {
      "shipToLocationAvailability": {
        "quantity": 30
      }
    }
  }'

Lấy mặt hàng trong kho

curl -X GET "https://api.ebay.com/sell/inventory/v1/inventory_item/SKU123" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Đăng bán sản phẩm

Tạo một ưu đãi

curl -X POST "https://api.ebay.com/sell/inventory/v1/offer" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "SKU123",
    "marketplaceId": "EBAY_US",
    "format": "FIXED_PRICE",
    "product": {
      "title": "Vintage Leather Messenger Bag"
    },
    "pricingSummary": {
      "price": {
        "currency": "USD",
        "value": "89.99"
      }
    },
    "listing": {
      "listingDuration": "GTC",
      "listingType": "CLASSIC"
    },
    " fulfillment": {
      "shippingProfileId": "SHIPPING_PROFILE_ID",
      " fulfillmentPolicyId": "FULFILLMENT_POLICY_ID",
      "paymentPolicyId": "PAYMENT_POLICY_ID"
    }
  }'

Các trường chính:

sku - SKU kho hàng của bạn
marketplaceId - EBAY_US, EBAY_UK, EBAY_DE, v.v.
format - FIXED_PRICE (Giá cố định) hoặc AUCTION (Đấu giá)
listingDuration - Thời gian đăng bán (GTC = good til canceled - tốt cho đến khi hủy)
price - Giá chào bán của bạn

Đăng ưu đãi

curl -X POST "https://api.ebay.com/sell/inventory/v1/offer/OFFER_ID/publish" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Rút danh sách sản phẩm

curl -X POST "https://api.ebay.com/sell/inventory/v1/offer/OFFER_ID/withdraw" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Quản lý đơn hàng

Lấy đơn hàng

curl -X GET "https://api.ebay.com/sell/fulfillment/v1/order?orderIds=ORDER_ID_1,ORDER_ID_2" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Lọc theo ngày:

curl -X GET "https://api.ebay.com/sell/fulfillment/v1/order?filter=creation_date_range:from:2026-01-01T00:00:00Z,to:2026-03-24T00:00:00Z" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Lấy chi tiết đơn hàng

curl -X GET "https://api.ebay.com/sell/fulfillment/v1/order/ORDER_ID" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Phản hồi đơn hàng:

{
  "orderId": "12-34567-89012",
  "orderPaymentStatus": "PAID",
  "pricingSummary": {
    "total": {
      "currency": "USD",
      "value": "94.99"
    }
  },
  "fulfillmentStartInstructions": [
    {
      "shippingStep": {
        "shipTo": {
          "fullName": "John Doe",
          "contactAddress": {
            "addressLine1": "123 Main St",
            "city": "Anytown",
            "stateOrProvince": "CA",
            "postalCode": "12345",
            "countryCode": "US"
          }
        }
      }
    }
  ],
  "lineItems": [
    {
      "lineItemId": "LINE_ITEM_ID",
      "sku": "SKU123",
      "quantity": 1,
      "title": "Vintage Leather Messenger Bag",
      "lineItemCost": {
        "currency": "USD",
        "value": "89.99"
      }
    }
  ]
}

Vận chuyển và thực hiện đơn hàng

Tạo nhãn vận chuyển

curl -X POST "https://api.ebay.com/sell/fulfillment/v1/order/ORDER_ID/shipping_fulfillment" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "lineItems": [
      {
        "lineItemId": "LINE_ITEM_ID",
        "quantity": 1
      }
    ],
    "shippingStep": {
      "shipFrom": {
        "fullName": "Your Name",
        "companyName": "Your Company",
        "contactAddress": {
          "addressLine1": "456 Warehouse Rd",
          "city": "San Jose",
          "stateOrProvince": "CA",
          "postalCode": "95101",
          "countryCode": "US"
        }
      }
    },
    "shippingCarrierCode": "USPS",
    "shippingMethodCode": "PRIORITY_MAIL",
    "trackingNumber": "9400111899223056789012"
  }'

Nhà vận chuyển:

USPS
UPS
FedEx
DHL

Quản lý trả hàng

Lấy chi tiết trả hàng

curl -X GET "https://api.ebay.com/sell/fulfillment/v1/return/RETURN_ID" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Xử lý một yêu cầu trả hàng

curl -X POST "https://api.ebay.com/sell/fulfillment/v1/return/RETURN_ID/decide" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "ACCEPT",
    "shipment": {
      "carrierId": "CARRIER_ID",
      "trackingNumber": "TRACKING_NUMBER"
    }
  }'

Giới hạn tốc độ và cách xử lý

eBay giới hạn các cuộc gọi API để ngăn chặn lạm dụng. Kiểm tra các tiêu đề (headers):

X-RateLimit-Limit - Số lượng yêu cầu tối đa cho phép
X-RateLimit-Remaining - Số yêu cầu còn lại trong khoảng thời gian
X-RateLimit-Reset - Dấu thời gian Unix khi giới hạn được đặt lại

async function makeEbayRequest(url, options, retries = 3) {
  for (let i = 0; i < retries; i++) {
    const response = await fetch(url, options)
    
    const remaining = response.headers.get('X-RateLimit-Remaining')
    if (remaining && parseInt(remaining) < 10) {
      console.warn('Giới hạn tốc độ thấp:', remaining)
    }
    
    if (response.status === 429) {
      const resetTime = response.headers.get('X-RateLimit-Reset')
      const waitTime = (parseInt(resetTime) - Date.now() / 1000) * 1000
      await sleep(waitTime)
      continue
    }
    
    return response
  }
  throw new Error('Vượt giới hạn tốc độ')
}

Kiểm tra với Apidog

API của eBay rất quan trọng đối với sản xuất. Hãy kiểm tra kỹ lưỡng trước khi thực hiện thay đổi trực tiếp.

1. Cài đặt môi trường

EBAY_APP_ID: your_app_id
EBAY_CERT_ID: your_cert_id
EBAY_ACCESS_TOKEN: stored_token
EBAY_REFRESH_TOKEN: stored_refresh
EBAY_MARKETPLACE_ID: EBAY_US
BASE_URL: https://api.ebay.com

2. Xác thực dữ liệu gửi đi (payloads) của danh sách sản phẩm

pm.test('Danh sách sản phẩm có các trường bắt buộc', () => {
  const requestBody = JSON.parse(pm.request.body.raw)
  pm.expect(requestBody).to.have.property('sku')
  pm.expect(requestBody).to.have.property('marketplaceId')
  pm.expect(requestBody.pricingSummary).to.have.property('price')
})

pm.test('Giá hợp lệ', () => {
  const requestBody = JSON.parse(pm.request.body.raw)
  const price = parseFloat(requestBody.pricingSummary.price.value)
  pm.expect(price).to.be.above(0)
})

3. Kiểm tra quy trình xử lý đơn hàng

pm.test('Phản hồi đơn hàng hợp lệ', () => {
  const response = pm.response.json()
  pm.expect(response).to.have.property('orderId')
  pm.expect(response.orderPaymentStatus).to.eql('PAID')
  pm.expect(response.lineItems).to.be.an('array')
})

Thử nghiệm API của eBay với Apidog - miễn phí

Các lỗi thường gặp và cách khắc phục

401 Không được ủy quyền

Nguyên nhân: Token đã hết hạn hoặc không hợp lệ.

Cách khắc phục: Sử dụng refresh token để lấy access token mới:

const response = await fetch('https://api.ebay.com/identity/v1/oauth2/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Authorization': 'Basic ' + Buffer.from(APP_ID + ':' + CERT_ID).toString('base64')
  },
  body: new URLSearchParams({
    grant_type: 'refresh_token',
    refresh_token: storedRefreshToken
  })
})

10002: Lỗi API - Access token không hợp lệ

Nguyên nhân: Access token đã hết hạn.

Cách khắc phục: Làm mới token ngay lập tức.

21916684: Mặt hàng không tồn tại

Nguyên nhân: Đang cố gắng cập nhật một SKU chưa được tạo.

Cách khắc phục: Tạo mặt hàng trong kho trước, sau đó tạo ưu đãi.

10003: SKU không hợp lệ

Nguyên nhân: Định dạng SKU không hợp lệ.

Cách khắc phục: SKU phải là duy nhất trong kho hàng của bạn và chỉ có thể chứa các ký tự chữ và số, dấu gạch ngang và dấu gạch dưới.

Giới hạn tốc độ (429)

Nguyên nhân: Quá nhiều yêu cầu.

Cách khắc phục: Triển khai chiến lược lùi lại (backoff). Giới hạn của eBay khác nhau tùy theo API và điểm cuối.

Các lựa chọn thay thế và so sánh

Tính năng	eBay	Amazon SP-API	Etsy
API Kho hàng	✓	✓	Giới hạn
API Danh sách sản phẩm	✓	✓	✓
API Đơn hàng	✓	✓	✓
API Thực hiện đơn hàng	✓	✓	Giới hạn
Gói miễn phí	Chương trình nhà phát triển	Giới hạn	Giới hạn
Độ phức tạp của API	Trung bình	Cao	Thấp

API của eBay dễ tiếp cận hơn so với Amazon nhưng ít tính năng hơn. Etsy là đơn giản nhất nhưng bị hạn chế đối với những người bán lớn hơn.

Các trường hợp sử dụng thực tế

Bán hàng đa kênh. Một người bán đăng sản phẩm trên eBay, Amazon và trang web riêng của họ. Kho hàng được đồng bộ hóa trên các nền tảng. Khi bán trên một kênh, số lượng sẽ giảm ở mọi nơi.

Tự động điều chỉnh giá. Người bán theo dõi đối thủ cạnh tranh và điều chỉnh giá qua API. Khi đối thủ hạ giá, giá của người bán sẽ tự động điều chỉnh để duy trì tính cạnh tranh.

Đăng bán hàng loạt. Một người bán với 10.000 mặt hàng tạo danh sách sản phẩm hàng loạt. API chấp nhận tải lên tệp CSV, tự động tạo hàng ngàn danh sách sản phẩm.

Kết luận

Dưới đây là những gì bạn đã học được:

Xác thực với OAuth 2.0 bằng thông tin xác thực ứng dụng
Quản lý kho hàng bằng SKU
Tạo và đăng bán sản phẩm
Xử lý đơn hàng và vận chuyển
Xử lý trả hàng
Kiểm tra với Apidog trước khi triển khai thực tế

Các bước tiếp theo của bạn:

Đăng ký Chương trình Nhà phát triển eBay
Tạo một ứng dụng và lấy thông tin xác thực
Triển khai luồng OAuth
Tạo mặt hàng đầu tiên trong kho của bạn
Đăng một danh sách sản phẩm thử nghiệm

Thử nghiệm API của eBay với Apidog - miễn phí

Tải ứng dụng

Câu hỏi thường gặp

Tôi có cần tài khoản doanh nghiệp để sử dụng API không?Có. API của eBay dành cho người bán đã được xác minh. Đăng ký tài khoản người bán và hoàn tất xác minh.

Sự khác biệt giữa kho hàng và ưu đãi là gì?Kho hàng lưu trữ thông tin sản phẩm (tiêu đề, mô tả, hình ảnh). Ưu đãi liên kết kho hàng với một thị trường kèm thông tin về giá cả và thực hiện đơn hàng. Nhiều ưu đãi có thể tham chiếu cùng một kho hàng.

Danh sách sản phẩm tồn tại trong bao lâu?Các danh sách sản phẩm với GTC (tốt cho đến khi hủy) vẫn hoạt động cho đến khi bạn rút chúng hoặc mặt hàng được bán hết.

Tôi có thể bán hàng quốc tế qua API không?Có. Đặt marketplaceId thành các giá trị khác nhau (EBAY_US, EBAY_UK, EBAY_DE, v.v.). Bạn sẽ cần tuân thủ các yêu cầu của từng thị trường.

Giới hạn tốc độ API là bao nhiêu?Giới hạn khác nhau tùy theo điểm cuối (endpoint) và cấp độ tài khoản của bạn. Kiểm tra các tiêu đề phản hồi để biết giới hạn hiện tại của bạn.

Làm cách nào để tôi có được nhãn vận chuyển?eBay cung cấp nhãn vận chuyển giảm giá thông qua API Thực hiện đơn hàng. Bạn tạo lô hàng và eBay sẽ tạo nhãn.