Dịch vụ tích hợp API eBay: Phạm vi, giới hạn và thay đổi 2026

Dịch vụ tích hợp API eBay thực sự bao gồm những gì?

Dịch vụ tích hợp API eBay kết nối hệ thống riêng của bạn (nền tảng cửa hàng, ERP, công cụ kho hoặc hệ thống back office tùy chỉnh) với eBay thông qua các API chính thức của eBay. Nhờ đó, dữ liệu sản phẩm đăng bán, tồn kho, đơn hàng và giao hàng được luân chuyển mà không cần nhân viên nhập lại thủ công trong Seller Hub. Đây là công việc vừa cần phát triển kỹ thuật vừa cần bảo trì liên tục, vì phía eBay thường xuyên thay đổi.

Mọi thông tin về eBay trên trang này đã được đối chiếu với tài liệu dành cho nhà phát triển của eBay vào ngày 29 tháng 9 năm 2026.

Một phạm vi triển khai đầy đủ gồm sáu phần:

• Ủy quyền: xin sự đồng ý của người bán, đồng thời lưu trữ và gia hạn OAuth token cho từng tài khoản eBay được kết nối.
• Đồng bộ sản phẩm đăng bán: ánh xạ dữ liệu sản phẩm vào danh mục, thuộc tính sản phẩm, chính sách kinh doanh và hình ảnh trên eBay, sau đó tạo và cập nhật listing.
• Đồng bộ tồn kho và giá: đẩy thay đổi về số lượng và giá đủ nhanh để tránh bán vượt tồn.
• Đồng bộ đơn hàng: lấy đơn hàng đã thanh toán về hệ thống, đồng thời gửi mã vận đơn và trạng thái hoàn tất đơn hàng ngược lại eBay.
• Quy trình sau bán hàng: hủy đơn, trả hàng, hoàn tiền và xử lý tranh chấp.
• Vận hành: xử lý giới hạn tốc độ gọi API, hàng đợi thử lại, cảnh báo và theo dõi thông báo ngừng hỗ trợ của eBay.

Hai phần cuối thường dễ bị bỏ sót trong báo giá nhất, nhưng lại quyết định liệu hệ thống tích hợp có tiếp tục hoạt động ổn định sau một năm hay không. Các phần dưới đây phân tích những điểm cần lưu ý của từng hạng mục.

Nên xây dựng trên những API eBay nào trong năm 2026?

eBay đang vận hành song song hai thế hệ API bán hàng. Các REST API (Inventory, Fulfillment, Account, Metadata, Taxonomy, Media, Notification và Feed) sử dụng JSON và OAuth 2.0. Trading API cũ dựa trên XML và vẫn cung cấp các lệnh như AddFixedPriceItem và GetOrders. Trên thực tế, phần lớn hệ thống tích hợp production vẫn cần sử dụng cả hai trong một thời gian, vì tài liệu tổng quan về Inventory API của eBay cũng liệt kê Trading API, Account API và Fulfillment API là các API bổ trợ cho Inventory API.

Quy tắc thực tế: mọi dự án mới nên bắt đầu trên REST API. Một hệ thống hiện có dùng Trading API chưa nhất thiết phải viết lại ngay trong quý này, nhưng mọi lệnh phụ thuộc vào đó cần được đối chiếu định kỳ với danh sách ngừng hỗ trợ, thay vì chỉ kiểm tra một lần lúc bắt đầu dự án.

Các API eBay ngừng hỗ trợ cần chuẩn bị trong năm 2026

eBay ngừng từng khả năng và từng sự kiện của Trading API theo từng lệnh, chứ không tắt toàn bộ trong một lần. Bảng dưới đây được lấy từ trang trạng thái ngừng hỗ trợ API của eBay và thể hiện lịch vẫn được công bố tại thời điểm kiểm tra.

Đã ngừng trong năm 2026: Trading API GetCategories (15 tháng 4), GetCategoryFeatures (4 tháng 6) và thông báo ItemMarkedPaid (22 tháng 6); Compliance API (30 tháng 3); toàn bộ Product API (15 tháng 8); cùng một số phương thức Post-Order API trong khoảng tháng 1 đến tháng 3.

Có hai xu hướng quan trọng hơn bất kỳ mốc thời gian đơn lẻ nào. Thứ nhất, thời gian thông báo chênh lệch rất lớn: khoảng một tháng đối với VeRO API và gần mười một tháng đối với UploadSiteHostedPictures. Thứ hai, một API thay thế thường được phân tách thành hai API: GetCategories được thay bằng Taxonomy kết hợp Metadata. Hệ thống tích hợp gắn cứng một lệnh cho mỗi nhiệm vụ sẽ bị hỏng từng phần, và việc khắc phục hiếm khi chỉ là thay một dòng mã.

OAuth trên eBay: token, sự đồng ý và những điểm tích hợp thường gặp lỗi

eBay cấp hai loại OAuth token và sự khác biệt này quyết định kiến trúc hệ thống. Hướng dẫn ủy quyền của eBay định nghĩa như sau: application token được tạo qua client credentials grant và dùng cho dữ liệu không gắn với người bán, chẳng hạn taxonomy và metadata. User token được tạo qua authorization code grant sau khi người bán đồng ý, và dùng cho mọi thao tác liên quan đến listing hoặc đơn hàng của người bán đó.

Access token có hiệu lực trong hai giờ (7.200 giây theo các phản hồi mẫu của eBay). Refresh token trong cùng tài liệu có thời hạn 47.304.000 giây, tương đương khoảng 18 tháng. Đây là thông tin xác thực thực sự được lưu trong cơ sở dữ liệu, vì vậy cần bảo vệ refresh token như một credential.

Điều gì khiến refresh token bị thu hồi?

• Người bán thay đổi tên người dùng hoặc mật khẩu eBay, khiến các refresh token đang hoạt động tự động bị thu hồi.
• Người bán tự thu hồi quyền truy cập trong trang tài khoản eBay.
• eBay thu hồi token vì các lý do riêng.
• Ứng dụng của bạn bổ sung scope. Mọi người bán phải đồng ý lại, vì vậy eBay khuyến nghị yêu cầu đồng thời các scope cần cho tính năng hiện tại và dự kiến.

Hệ quả khi thiết kế hệ thống

Hãy coi trạng thái “người bán cần kết nối lại” là một trạng thái bình thường, không phải lỗi bất thường. Hệ thống nên tạm dừng đồng bộ cho người bán đó, đánh dấu trong giao diện hoặc gửi email thông báo, rồi tiếp tục sau khi họ cấp quyền lại, thay vì liên tục thử lại các lệnh lỗi cho đến khi chạm giới hạn.

Hãy refresh token theo nhu cầu. Khuyến nghị của eBay là gia hạn token sau khi nhận lỗi invalid-token thay vì theo dõi thời điểm hết hạn của từng token. Phép tính cũng cho thấy lý do: nếu refresh token của mọi người bán mỗi hai giờ, mỗi người bán sẽ tiêu tốn 12 lượt refresh mỗi ngày, khiến giới hạn 50.000 lượt/ngày cạn ở khoảng 4.000 người bán được kết nối. Hãy thêm khóa theo từng người bán để các worker chạy song song không cùng refresh một token.

Nếu vẫn gọi endpoint Trading API bằng Auth'n'Auth token cũ, cần lưu ý các token này có thời hạn 18 tháng, đi kèm cảnh báo hết hạn trước bảy ngày và sẽ trả về lỗi 932 khi hết hạn hoàn toàn. eBay khuyến nghị sử dụng OAuth ngay cả với các API truyền thống.

Đồng bộ listing và tồn kho bằng Inventory API

Inventory API mô hình hóa một listing theo nhiều lớp. Người bán cần ít nhất một địa điểm tồn kho, sau đó là inventory item (SKU duy nhất trên mỗi người bán), rồi một offer tham chiếu đến marketplace, địa điểm, danh mục và ba chính sách kinh doanh. Việc publish offer sẽ đưa listing lên trạng thái hoạt động. Sản phẩm có biến thể cần thêm inventory item group. Thứ tự gọi là createInventoryLocation, createOrReplaceInventoryItem, createOffer, publishOffer.

Dưới đây là những điểm thường xuất hiện trong buổi xác định phạm vi:

• Đây là quyết định một chiều. Tổng quan Inventory API của eBay nêu rõ listing được tạo qua Inventory API không thể chỉnh sửa trong Seller Hub hoặc bất kỳ nền tảng listing nào khác. Hãy quyết định hệ thống nào sở hữu dữ liệu listing trước khi vận hành chính thức và thông báo rõ cho nhân viên người bán.
• Chính sách kinh doanh là bắt buộc. Người bán phải tham gia chương trình, và mỗi offer cần có chính sách thanh toán, hoàn tất đơn hàng và trả hàng. Tài khoản chưa từng tham gia sẽ lỗi ở offer đầu tiên, chứ không phải lúc kết nối.
• SKU là định danh. SKU phải duy nhất trong toàn bộ tồn kho của người bán đó. Việc ánh xạ SKU cần ổn định; nếu không, lần nhập lại sẽ tạo bản sao thay vì cập nhật.
• Một số trường chỉ trở thành bắt buộc khi publish. Có trường tùy chọn trong lúc xây dựng offer nhưng bắt buộc để publish, vì vậy hãy xác thực trước khi publish thay vì chờ đến khi lệnh thất bại.
• Có thể di chuyển listing hiện có nhưng kèm điều kiện. bulkMigrateListings chuyển listing đang hoạt động thành đối tượng Inventory API, nhưng chỉ áp dụng cho listing đáp ứng thêm một số yêu cầu. Hãy dự trù xử lý riêng cho các listing không đạt điều kiện.
• Tồn kho bằng 0 không nên kết thúc listing. Khi bật Out-of-Stock Control, listing có số lượng bằng 0 vẫn hoạt động tối đa 90 ngày nhưng sẽ bị ẩn khỏi kết quả tìm kiếm.

Quy tắc danh mục cũng có thể thay đổi. Cổng dành cho nhà phát triển của eBay đã thông báo rằng listing Apparel và Footwear có dữ liệu kích thước không chuẩn, thiếu hoặc chưa đầy đủ có thể bị chặn hoặc ẩn từ tháng 8 năm 2026; đồng thời thông tin tình trạng sản phẩm theo chuẩn trở thành bắt buộc trong một số danh mục tiền xu từ tháng 5. Hãy đặt quy tắc theo từng danh mục trong cấu hình thay vì hard-code, để thay đổi quy tắc chỉ cần sửa dữ liệu thay vì triển khai lại. Inventory Mapping API mới của eBay, có khả năng chuyển dữ liệu sản phẩm hiện có thành bản xem trước listing, cũng đáng được cân nhắc cho bước ánh xạ.

Đồng bộ đơn hàng và giao hàng bằng Fulfillment API

Theo mô hình của eBay, đơn hàng được tạo sau checkout, các line item được gom vào package, còn việc xử lý và giao từng package được gọi là fulfillment. Hệ thống tích hợp đọc đơn hàng bằng getOrders, sau đó ghi thông tin vận chuyển bằng createShippingFulfillment. Tốc độ hoàn tất đơn hàng không chỉ mang tính hình thức: tài liệu eBay lưu ý rằng trạng thái của người bán một phần phụ thuộc vào lịch sử hoàn tất đơn đúng hạn.

Một giới hạn được tài liệu ghi rõ thường gây ra các báo cáo lỗi không chính xác. Fulfillment API chỉ bao gồm các giao dịch đã hoàn tất checkout, còn getOrders không trả về các giao dịch đang chờ thanh toán yêu cầu thanh toán trước. Nếu số lượng đơn nhập vào khác Seller Hub, hãy kiểm tra đơn chưa thanh toán trước khi tìm lỗi đồng bộ.

Để cập nhật nhanh, Notification API cho phép đăng ký endpoint đích và subscribe vào các topic, để eBay đẩy sự kiện thay vì buộc hệ thống phải polling. Tuy nhiên, không nên chỉ dựa vào push: hãy chạy thêm một lượt polling với khoảng thời gian nhìn lại để dự phòng, đồng thời chuẩn bị cho việc các sự kiện thông báo Trading API cũ tiếp tục bị loại bỏ (ItemMarkedPaid đã ngừng hoạt động).

Hoàn tiền cần có kế hoạch kiểm thử riêng. issueRefund nằm trong Fulfillment API, và với người bán ở EU và UK, lệnh này yêu cầu chữ ký số (xem phần tiếp theo).

Giới hạn gọi API, kiểm tra tăng trưởng và yêu cầu tuân thủ

Ba yêu cầu của eBay ảnh hưởng trực tiếp đến tiến độ và ngân sách tích hợp, nhưng không yêu cầu nào thể hiện rõ trong một bản demo sandbox.

Giới hạn gọi khác nhau theo từng API, vì vậy hãy đọc bảng công bố của eBay cho các API bạn sử dụng. Theo dõi mức tiêu thụ bằng getRateLimits trong Developer Analytics API và nộp Application Growth Check trước khi tiến sát giới hạn; eBay không thu phí cho quy trình này.

Yêu cầu chữ ký là phần nặng nhất về kỹ thuật. Cơ chế này tuân theo IETF RFC 9421 và RFC 9530, đồng thời bổ sung bốn header (x-ebay-signature-key, Content-Digest khi có payload, Signature và Signature-Input). Key được lấy từ Key Management API của eBay. eBay không lưu private key, nên nếu làm mất key, bạn phải tạo một cặp mới. Để kiểm thử trong sandbox, domicile của test user phải được đặt tại một quốc gia EU hoặc UK; nếu không, chữ ký sẽ không bao giờ được yêu cầu hay kiểm tra.

Tự xây dựng, dùng connector hay thuê dịch vụ tích hợp?

Không có lựa chọn đúng cho mọi doanh nghiệp, và connector thường là bước đầu phù hợp với một catalog tiêu chuẩn. Điều quan trọng là xác định khi nào yêu cầu của bạn vượt quá khả năng của từng lựa chọn.

Nếu catalog hoặc quy trình của bạn đã vượt quá khả năng của connector, dịch vụ tích hợp marketplace tùy chỉnh của Netalith có thể đáp ứng, bao gồm listing, tồn kho, đơn hàng và mã vận đơn eBay cùng Amazon SP-API, Walmart, Etsy và các kênh khác.

Nên hỏi gì nhà cung cấp dịch vụ tích hợp eBay trước khi ký hợp đồng?

1. Dịch vụ sẽ sử dụng những API eBay nào? Bất kỳ phụ thuộc nào vào lệnh Trading API nằm trong danh sách ngừng hỗ trợ đều có thể phát sinh công việc làm lại.
2. Hệ thống sẽ chạy bằng bộ developer key của ai? Bộ key quyết định giới hạn gọi API và trạng thái Application Growth Check của bạn.
3. Refresh token bị thu hồi sẽ được xử lý thế nào? Câu trả lời cần mô tả quy trình cấp quyền lại, không phải thử lại liên tục.
4. Hệ thống nào sở hữu dữ liệu listing? Listing của Inventory API không thể chỉnh sửa trong Seller Hub sau đó.
5. Đơn chờ thanh toán có quan trọng với bạn không? Fulfillment API không đưa các đơn này vào getOrders.
6. Bạn có bán cho người mua ở EU hoặc UK thông qua người bán tại EU hoặc UK không? Nếu có, hoàn tiền và dữ liệu tài chính sẽ cần chữ ký số.
7. Điều gì xảy ra khi bị giới hạn tốc độ gọi hoặc eBay gặp sự cố? Hãy tìm hiểu về hàng đợi, cơ chế backoff và cảnh báo.
8. Ai theo dõi thông báo ngừng hỗ trợ của eBay và việc đó đã nằm trong chi phí chưa?
9. Bạn nhận được gì khi bàn giao? Mã nguồn, tài liệu, bộ kiểm thử và quyền sở hữu key.

Xác định phạm vi tích hợp eBay cùng Netalith

Hãy gửi cho Netalith thông tin về nền tảng, các quy trình eBay cần hỗ trợ (listing, tồn kho, đơn hàng, mã vận đơn, hoàn tiền) và thị trường bạn đang bán. Netalith sẽ xác định phạm vi công việc. Chi phí được tính theo phạm vi, không theo gói cố định. Yêu cầu báo giá miễn phí để bắt đầu.