Dịch vụ tích hợp Etsy API: Phạm vi, quyền truy cập và cách thuê

Dịch vụ tích hợp Etsy API bao gồm những gì?

Dịch vụ tích hợp Etsy API kết nối dữ liệu của cửa hàng Etsy — như sản phẩm đăng bán, hàng tồn kho, đơn hàng và thông tin theo dõi — với các hệ thống bạn đang sử dụng thông qua Etsy Open API v3, đồng thời duy trì đồng bộ giữa hai bên. Hệ thống được kết nối thường là cửa hàng trực tuyến, ERP hoặc Odoo, công cụ vận chuyển hay nền tảng bán hàng đa kênh.

Hãy xác định phạm vi theo từng nhóm công việc, thay vì chỉ gọi chung là “kết nối Etsy”. Mỗi hàng dưới đây là một hạng mục riêng với các rủi ro vận hành khác nhau, đồng thời tương ứng với một nhóm quyền cụ thể trong mô hình OAuth của Etsy.

Có hai việc nằm ngoài phạm vi của một hoạt động tích hợp hợp lệ. Việc scrape các trang Etsy để lấy dữ liệu mà API không cung cấp bị cấm theo tiêu chí truy cập thương mại của Etsy. Ngoài ra, Open API v3 không có endpoint để mua nhãn vận chuyển, vì vậy người bán vẫn phải tự mua và in nhãn.

Bạn cần cấp truy cập Etsy API nào: Seller App, Personal App hay Commercial Access?

Etsy phân quyền API theo loại ứng dụng. Lựa chọn này quyết định ai có thể kết nối, thời gian được phê duyệt và việc tích hợp có thể phục vụ nhiều hơn một cửa hàng hay không. Tính đến ngày 29 tháng 9 năm 2026, tài liệu dành cho nhà phát triển của Etsy xác định ba cấp độ.

Quy tắc chúng tôi thường áp dụng là: nếu tích hợp chỉ phục vụ một cửa hàng, chủ cửa hàng nên đăng ký Seller App bằng chính tài khoản Etsy của họ, còn nhà phát triển xây dựng dựa trên key đó. Etsy chỉ phê duyệt Seller App cho người bán chưa có ứng dụng nào khác đang hoạt động, và ứng dụng chỉ có thể xác thực với cửa hàng đã đăng ký. Vì vậy, agency không thể và cũng không nên dùng một key do agency sở hữu cho nhiều cửa hàng khách hàng. Lợi ích đi kèm là quyền sở hữu rõ ràng: thông tin xác thực và hệ thống tích hợp vẫn thuộc về khách hàng khi hợp đồng kết thúc.

Nếu bạn đang xây dựng một sản phẩm để những người bán khác kết nối, trước tiên bạn cần Personal App, sau đó gửi yêu cầu Commercial Access. Các tiêu chí xét duyệt được công bố bao gồm tuân thủ API Terms of Use và chính sách caching, không scrape màn hình, sử dụng OAuth cho mọi chức năng chạm đến dữ liệu thành viên riêng tư, đặt tên và hình ảnh ứng dụng theo chính sách thương hiệu của Etsy, đồng thời hiển thị nổi bật thông báo rằng Etsy không xác nhận hoặc chứng nhận ứng dụng. Các ứng dụng thương mại sử dụng transactions_r cũng phải yêu cầu riêng trường buyer_email. Etsy không công bố thời gian xét duyệt cụ thể, chỉ cho biết thời gian thay đổi tùy trường hợp sử dụng, vì vậy hãy xem việc phê duyệt là một phụ thuộc trên đường găng của dự án. Bạn có thể xem đầy đủ tiêu chí trong phần giới thiệu Open API v3 của Etsy.

Tự xây dựng, dùng ứng dụng có sẵn hay thuê dịch vụ tích hợp Etsy API?

Có ba hướng triển khai thực tế. Lựa chọn phù hợp phụ thuộc vào mức độ quy trình Etsy của bạn khác với luồng đăng sản phẩm và xử lý đơn hàng tiêu chuẩn.

Etsy hiếm khi là kênh bán hàng duy nhất. Dịch vụ tích hợp sàn thương mại điện tử cho Etsy, Amazon SP-API, eBay, Walmart và Temu của Netalith bao gồm Etsy cùng các kênh đó, giúp thiết kế logic tồn kho và đơn hàng một lần cho tất cả kênh thay vì làm riêng cho từng sàn.

Một cách nhanh để đánh giá việc tùy chỉnh có đáng đầu tư hay không là liệt kê những tình huống mà ứng dụng tiêu chuẩn buộc bạn phải sửa dữ liệu thủ công, chẳng hạn bán vượt tồn sau khi thay đổi biến thể hoặc cập nhật thông tin theo dõi muộn. Nếu danh sách ngắn, hãy dùng ứng dụng có sẵn. Nếu danh sách dài, bản thân hệ thống tích hợp đã trở thành một sản phẩm và cần có phạm vi công việc bằng văn bản.

Xác thực Etsy API hoạt động như thế nào và thường gặp lỗi gì?

Etsy Open API v3 sử dụng đồng thời hai thông tin xác thực: API key trong mọi request và token OAuth 2.0 cho mọi dữ liệu riêng tư hoặc thao tác ghi. Dưới đây là những điểm nhà phát triển cần biết.

Ba lỗi dưới đây chiếm phần lớn các ticket dạng “tích hợp đột nhiên ngừng hoạt động”. Thứ nhất, phản hồi refresh không được lưu lại, khiến lần refresh tiếp theo dùng token cũ và người bán phải kết nối lại. Hãy lưu phiên bản mới nhất trong mỗi phản hồi và cảnh báo sớm hơn mốc 90 ngày đối với mọi cửa hàng chưa refresh. Thứ hai, scope được cấp có thể là một phần của scope yêu cầu, vì vậy hãy kiểm tra trường scope trong phản hồi token thay vì mặc định rằng bạn có quyền ghi. Thứ ba, thiếu scope cho một nhóm công việc thường chỉ gây lỗi ở một số lệnh gọi cụ thể, trông giống lỗi ngẫu nhiên cho đến khi có người đối chiếu các scope.

Một điểm dễ gây nhầm trong tài liệu: một số ví dụ hướng dẫn chỉ gửi keystring trong x-api-key, trong khi trang xác thực quy định keystring và shared secret phải được nối bằng dấu hai chấm. Hãy làm theo trang xác thực.

Bạn có thể đồng bộ gì qua Etsy API: endpoint và scope

Mọi đường dẫn dưới đây đều nằm dưới https://api.etsy.com/v3/application. Hãy xác nhận scope chính xác của từng endpoint trong tài liệu tham chiếu API của Etsy trước khi xin quyền từ người bán, vì yêu cầu nhiều scope hơn nhu cầu thực tế sẽ làm giảm khả năng người bán phê duyệt.

Nội dung tối thiểu của một sản phẩm vật lý bản nháp gồm quantity, title, description, price, who_made, when_made và taxonomy_id, cùng với shipping_profile_id và readiness_state_id. Cần có image_ids trước khi sản phẩm có thể được kích hoạt. Chuỗi phụ thuộc gồm hồ sơ vận chuyển, hồ sơ thời gian xử lý, taxonomy và hình ảnh là lý do việc tự động hóa sản phẩm đầu tiên thường mất nhiều thời gian hơn so với những gì phần nội dung request gợi ý.

Dùng webhook hay polling cho đơn hàng Etsy?

Etsy hiện đã cung cấp webhook, vì vậy hệ thống tích hợp không còn phải polling để tìm từng đơn hàng mới. Tài liệu webhook của Etsy liệt kê bốn sự kiện, tất cả đều liên quan đến đơn hàng.

Payload chỉ là một con trỏ, không phải toàn bộ đơn hàng: nó chứa event_type, resource_url và shop_id, sau đó mã của bạn gọi resource_url để lấy receipt. Tài liệu cho biết webhook có sẵn cho commercial app và personal app. Tài liệu không đề cập Seller App, vì vậy hãy xác nhận trong developer portal trước khi thiết kế tích hợp Seller App dựa trên webhook.

Mỗi lần gửi đều được ký. Nội dung được ký là webhook-id, webhook-timestamp và raw body được nối bằng dấu chấm; key là signing secret của bạn sau khi bỏ tiền tố whsec_ và giải mã phần còn lại bằng base64; chữ ký là HMAC-SHA256 được mã hóa base64. Ví dụ trình xác minh hoạt động bằng Python:

import base64, hashlib, hmac, time

def verify_etsy_webhook(secret, headers, raw_body, tolerance=300):
    msg_id = headers["webhook-id"]
    ts = headers["webhook-timestamp"]
    if abs(time.time() - int(ts)) > tolerance:
        return False  # stale or replayed
    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{msg_id}.{ts}.".encode() + raw_body
    expected = base64.b64encode(
        hmac.new(key, signed, hashlib.sha256).digest()
    ).decode()
    # header may hold several signatures; drop a version prefix if present
    return any(
        hmac.compare_digest(expected, part.split(",", 1)[-1])
        for part in headers["webhook-signature"].split()
    )

Hãy xác minh trên raw bytes trước khi phân tích JSON và dùng webhook-id làm khóa idempotency, vì Etsy giữ nguyên id này trong các lần thử lại. Nếu endpoint của bạn gặp lỗi, Etsy sẽ thử lại theo lịch: ngay lập tức, sau đó 5 giây, 5 phút, 30 phút, 2 giờ, 5 giờ và 10 giờ — hai lần ở mỗi mốc cuối — tổng cộng khoảng 27,5 giờ từ lần thử đầu tiên đến lần cuối.

Đừng loại bỏ polling hoàn toàn. Các sự kiện được tài liệu hóa chỉ bao phủ đơn hàng, vì vậy thay đổi về sản phẩm đăng bán và tồn kho vẫn cần được đọc theo lịch. Ngoài ra, một lượt đối soát so sánh danh sách đơn hàng của bạn với Etsy sẽ giúp phát hiện những gì endpoint bị lỗi đã bỏ sót.

Giới hạn tốc độ Etsy API và cách tích hợp tốt tránh vượt giới hạn

Etsy áp dụng giới hạn theo từng ứng dụng, tức theo từng API key, dưới dạng số truy vấn mỗi giây (QPS) và số truy vấn mỗi ngày (QPD). Giới hạn theo ngày là cửa sổ trượt 24 giờ, không phải đặt lại vào nửa đêm, nên quota được giải phóng liên tục khi các request cũ hết thời hạn. Các con số thực tế của ứng dụng được hiển thị trong Etsy Developer Portal.

Hệ quả thiết kế quan trọng nhất là ngân sách thuộc về key, không thuộc về cửa hàng. Mọi cửa hàng kết nối qua cùng một ứng dụng đều dùng chung một pool, vì vậy một người bán chạy thao tác đăng lại hàng loạt có thể làm các cửa hàng khác cạn quota. Tích hợp nhiều cửa hàng cần có hàng đợi request dùng chung với cơ chế phân bổ công bằng; các lệnh gọi đơn hàng và theo dõi nên được ưu tiên hơn việc làm mới catalog.

• Mọi phản hồi thành công đều trả về x-limit-per-day và x-remaining-today (cùng các giá trị tương đương theo giây), vì vậy hãy ghi log và cảnh báo trước khi chạm mức 0.
• Etsy kiểm tra QPS trước, sau đó đến QPD. Vượt một trong hai giới hạn sẽ trả về 429 cùng header retry-after.
• Hãy xem retry-after là một giá trị ước tính và bổ sung exponential backoff kèm jitter để nhiều worker không thử lại đồng thời.
• Cache các dữ liệu hiếm khi thay đổi, chẳng hạn taxonomy node và hồ sơ vận chuyển.
• Cần hạn mức cao hơn? Hãy gửi email đến [email protected] kèm mô tả ứng dụng và ước tính QPD/QPS. Etsy yêu cầu cả hai thông tin này.

Các điểm dễ lỗi của Etsy API làm hỏng đồng bộ sản phẩm và đơn hàng

Những điểm dưới đây được tổng hợp từ các hướng dẫn chính thức của Etsy và phản ánh các vị trí mà tích hợp thường lỗi sau lần thử nghiệm đầu tiên. Một điểm phụ thuộc vào ngày tháng: cách xử lý video thay đổi vào ngày 21 tháng 10 năm 2026.

Cần hỏi gì trước khi thuê nhà cung cấp dịch vụ tích hợp Etsy API?

Những câu hỏi dưới đây giúp phân biệt nhà cung cấp từng vận hành tích hợp Etsy thực tế với người chỉ mới đọc tài liệu một lần.

1. Tài khoản nhà phát triển Etsy và key sẽ thuộc về ai? Với một cửa hàng, chúng nên thuộc về bạn thông qua Seller App.
2. Bạn dự định dùng cấp truy cập nào và điều gì xảy ra nếu Etsy từ chối Commercial Access?
3. Refresh token được lưu ở đâu và hệ thống cảnh báo bạn như thế nào trước khi cửa hàng cần kết nối lại?
4. Bạn phân bổ ngân sách giới hạn tốc độ theo từng key ra sao và xử lý thế nào khi nhận 429?
5. Bạn sử dụng webhook, đối soát theo lịch hay cả hai?
6. Bạn ánh xạ biến thể, SKU và số lượng giữa Etsy với hệ thống của tôi như thế nào?
7. Điều gì xảy ra khi đồng bộ thất bại: thử lại, dead-letter queue hay cảnh báo cho con người?
8. Khi bàn giao, tôi sẽ nhận được gì: source code, ghi chú môi trường hay runbook?

Nếu bạn đã biết Etsy cần kết nối với những hệ thống nào, hãy mô tả trong biểu mẫu nhận báo giá miễn phí của Netalith. Công việc Etsy được tính phí theo phạm vi, nên yêu cầu càng cụ thể thì báo giá càng chính xác.