DEV Community

Cover image for Hướng Dẫn Sử Dụng eBay APIs Hiệu Quả
Sebastian Petrus
Sebastian Petrus

Posted on • Originally published at apidog.com

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

TL;DR

API của eBay cho phép bạn tự động hóa quản lý kho hàng, danh sách sản phẩm, đơn hàng và thanh toán. Xác thực qua OAuth 2.0, thao tác với các endpoint api.ebay.com/sell, và cần xử lý giới hạn tốc độ cẩn thận. Để kiểm thử, hãy dùng Apidog để xác thực payload của danh sách sản phẩm, kiểm tra luồng xử lý đơn hàng, và đảm bảo tích hợp xử lý rate limit linh hoạt.

Dùng thử Apidog ngay hôm nay

Giới thiệu

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

Các API chính:

  • Inventory API – Quản lý kho hàng
  • Listing API – Tạo/quản lý danh sách sản phẩm
  • Order API – Xử lý đơn hàng, vận chuyển
  • Fulfillment API – Thực hiện vận chuyển
  • Analytics API – Báo cáo bán hàng

💡 Nếu bạn tích hợp với eBay, Apidog giúp kiểm tra việc tạo danh sách, xác thực phản hồi đơn hàng, và đảm bảo xử lý đúng rate limit/lỗi.

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

Sau bài này, bạn sẽ:

  • Xác thực với eBay OAuth 2.0
  • Tạo/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/hoàn tiền
  • Kiểm thử với Apidog

Xác thực với OAuth 2.0

eBay sử dụng OAuth 2.0. Hãy tạo ứng dụng trong Developer Program.

eBay OAuth

Tạo ứng dụng

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

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
Enter fullscreen mode Exit fullscreen mode

Bước 2: Nhận mã ủy quyền

Sau khi người dùng ủy quyền, bạn nhận được mã tại redirect URI.

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()
Enter fullscreen mode Exit fullscreen mode

Scopes cần thiết

  • https://api.ebay.com/oauth/api_scope/sell.inventory – Quản lý kho
  • 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

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"
    }
  }'
Enter fullscreen mode Exit fullscreen mode

Tạo 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
      }
    }
  }'
Enter fullscreen mode Exit fullscreen mode

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
      }
    }
  }'
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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

Tạo ư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"
    }
  }'
Enter fullscreen mode Exit fullscreen mode

Các trường chính:

  • sku – SKU kho của bạn
  • marketplaceId – EBAY_US, EBAY_UK, EBAY_DE,...
  • format – FIXED_PRICE hoặc AUCTION
  • listingDuration – Ví dụ: GTC
  • price – Giá bán

Đăng ưu đãi 

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

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"
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

Ví dụ 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"
      }
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

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"
  }'
Enter fullscreen mode Exit fullscreen mode

Hãng vận chuyển phổ biế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"
Enter fullscreen mode Exit fullscreen mode

Xử lý 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"
    }
  }'
Enter fullscreen mode Exit fullscreen mode

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

eBay giới hạn số lượng request API. Kiểm tra các headers:

  • X-RateLimit-Limit – Số request tối đa
  • X-RateLimit-Remaining – Số request còn lại
  • X-RateLimit-Reset – Unix timestamp reset

Xử lý tự động backoff khi bị chặn:

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 độ')
}
Enter fullscreen mode Exit fullscreen mode

Kiểm tra với Apidog

API của eBay ảnh hưởng trực tiếp đến vận hành. Phải kiểm thử kỹ càng trước khi triển khai.

Apidog test

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
Enter fullscreen mode Exit fullscreen mode

2. Xác thực payload 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)
})
Enter fullscreen mode Exit fullscreen mode

3. Kiểm tra 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')
})
Enter fullscreen mode Exit fullscreen mode

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

Các lỗi thường gặp và cách xử lý

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

  • Nguyên nhân: Token hết hạn/không hợp lệ.
  • Khắc phục: Làm mới 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: 'refresh_token',
    refresh_token: storedRefreshToken
  })
})
Enter fullscreen mode Exit fullscreen mode

10002: API Access token không hợp lệ

  • Nguyên nhân: Token hết hạn.
  • Khắc phục: Làm mới token ngay.

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

  • Nguyên nhân: Cập nhật SKU chưa tạo.
  • Khắc phục: Tạo inventory item trước, rồi mới tạo offer.

10003: SKU không hợp lệ

  • Nguyên nhân: Định dạng SKU sai.
  • Khắc phục: SKU phải duy nhất, chỉ chứa chữ, số, gạch ngang, gạch dưới.

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

  • Nguyên nhân: Quá nhiều request.
  • Khắc phục: Triển khai backoff. Giới hạn tùy endpoint/tài khoản.

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 eBay dễ tiếp cận hơn Amazon, nhưng Amazon nhiều tính năng hơn. Etsy đơn giản nhất nhưng hạn chế cho seller lớn.

Trường hợp sử dụng thực tế

  • Bán hàng đa kênh: Đồng bộ kho giữa eBay, Amazon, website riêng.
  • Tự động điều chỉnh giá: Theo dõi đối thủ và cập nhật giá tự động qua API.
  • Đăng bán hàng loạt: Upload CSV, tự động tạo hàng loạt danh sách sản phẩm.

Kết luận

Bạn đã nắm được:

  • Xác thực OAuth 2.0 bằng app credentials
  • Quản lý kho bằng SKU
  • Tạo và đăng bán sản phẩm
  • Xử lý đơn hàng, vận chuyển, trả hàng
  • Kiểm thử với Apidog trước khi live

Các bước tiếp theo:

  1. Đăng ký Developer Program eBay
  2. Tạo ứng dụng, lấy credentials
  3. Triển khai luồng OAuth
  4. Tạo inventory item đầu tiên
  5. Đăng thử một danh sách sản phẩm

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

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

Tôi có cần tài khoản doanh nghiệp để dùng API không?

Có. API eBay chỉ dành cho seller đã xác minh.

Phân biệt inventory và offer?

Inventory chứa thông tin sản phẩm. Offer liên kết inventory với marketplace, kèm giá và chính sách. Nhiều offer có thể dùng chung một inventory.

Danh sách sản phẩm tồn tại bao lâu?

Với GTC (good til canceled), danh sách hoạt động đến khi bạn rút hoặc hết hàng.

Có thể bán quốc tế qua API không?

Có. Đặt marketplaceId thành EBAY_US, EBAY_UK, EBAY_DE,... và tuân thủ yêu cầu từng thị trường.

Giới hạn tốc độ API là bao nhiêu?

Khác nhau tùy endpoint và tài khoản. Kiểm tra header response để biết chi tiết.

Cách lấy nhãn vận chuyển?

eBay cung cấp nhãn vận chuyển giảm giá qua Fulfillment API. Bạn tạo lô hàng, eBay tạo nhãn.

Top comments (0)