Shopee (Seller)¶
Đang chạy production
Kết nối qua nút Cấp quyền trong portal — không còn quy trình riêng qua
Logidata. shopee là app ERP/bán hàng; quảng cáo và affiliate là hai nền
tảng riêng, xem Shopee Ads và Shopee
Affiliate.
Base URL:
Đường dẫn, tham số và response giống hệt Shopee Open Platform
v2. Gốc là
https://partner.shopeemobile.com.
Điều Logidata làm hộ bạn¶
Shopee là nền tảng tốn công nhất trong nhóm — ba việc riêng biệt phải làm đúng cùng lúc trên mỗi request:
| Việc | Gọi thẳng Shopee | Qua Logidata |
|---|---|---|
| Đăng ký partner app + chờ duyệt | Bạn làm | Đã có |
Ký HMAC-SHA256 (partner_id + path + timestamp + token + shop) |
Bạn viết | Tự động, ký lại trên MỖI request |
access_token hết hạn định kỳ — phải refresh trước khi chết |
Bạn dựng cron + xử lý đua refresh | Tự động, chạy nền định kỳ, có khoá phân tán |
| Mỗi loại dữ liệu dùng một cặp khoá partner khác nhau | Bạn quản lý nhiều bộ khoá | Chọn theo đường dẫn |
| Authorize lại khi shop thu hồi quyền | Bạn dựng lại luồng | Bấm Cấp lại quyền trên portal |
Token Shopee hết hạn — đây là nguồn lỗi số một của tích hợp tự viết
Khác TikTok Ads (token dài hạn), Shopee cấp access_token sống ngắn kèm
refresh_token. Nếu job refresh chết vào cuối tuần, pipeline im lặng dừng
và bạn mất dữ liệu cho tới thứ Hai. Qua Logidata, việc refresh chạy nền và
được khoá để nhiều tiến trình không cùng refresh làm hỏng token.
Nhóm dữ liệu¶
Allowlist chỉ đọc, gồm các endpoint Logidata đã dùng thật:
| Nhóm | Đường dẫn gốc | Dùng để |
|---|---|---|
| Danh sách đơn | /api/v2/order/get_order_list |
Đơn theo khoảng thời gian và trạng thái |
| Chi tiết đơn | /api/v2/order/get_order_detail |
Sản phẩm, số lượng, giá, khuyến mãi trong đơn |
| Đối soát | /api/v2/payment/get_escrow_detail |
Tiền thực nhận sau phí sàn, phí vận chuyển, voucher |
| Hoàn / trả — danh sách | /api/v2/returns/get_return_list |
Danh sách yêu cầu trả hàng |
| Hoàn / trả — chi tiết | /api/v2/returns/get_return_detail |
Chi tiết một yêu cầu trả hàng |
| Giao dịch ví | /api/v2/payment/get_wallet_transaction_list |
Lịch sử giao dịch ví Shopee của shop |
| Vận đơn — tracking info | /api/v2/logistics/get_tracking_info |
Trạng thái vận chuyển theo đơn |
| Vận đơn — mã vận đơn | /api/v2/logistics/get_tracking_number |
Mã vận đơn của một đơn hàng |
| Thông tin shop | /api/v2/shop/get_shop_info |
Tên, trạng thái, khu vực của shop |
| Đánh giá | /api/v2/product/get_comment |
Bình luận/đánh giá sản phẩm |
Quảng cáo Shopee tách thành nền tảng riêng — xem Shopee Ads.
Khác biệt cần biết trước khi thiết kế pipeline¶
get_escrow_detail là một request cho mỗi đơn. Không có bản gọi theo lô.
Một shop 600 đơn/ngày, kéo cửa sổ 2 ngày, chạy 4 lần/ngày ⇒ khoảng 144.000
lượt gọi/tháng cho một shop. So sánh: một Business Center TikTok Ads chỉ tốn
khoảng 1.200 lượt/tháng. Chênh lệch gấp hơn 100 lần — hãy chọn gói theo hồ
sơ Shopee của bạn, đừng chọn theo hồ sơ quảng cáo.
Tiền thực nhận không nằm trong đơn hàng. get_order_detail cho bạn giá bán;
chỉ get_escrow_detail mới cho bạn số tiền Shopee thực trả sau khi trừ phí,
voucher và trợ giá. Báo cáo doanh thu dựng từ đơn hàng đơn thuần sẽ sai lệch
đáng kể — đây là lỗi phổ biến nhất khi tự dựng báo cáo Shopee.
Cửa sổ thời gian bị giới hạn. Các endpoint theo thời gian của Shopee giới hạn độ dài mỗi lần gọi. Chia truy vấn lịch sử dài thành nhiều cửa sổ liên tiếp.
Shopee Ads và Shopee Affiliate¶
Quảng cáo và tiếp thị liên kết đi qua hai partner app riêng của Shopee (khoá
riêng, cấp quyền riêng trên portal), nên có tên nền tảng riêng —
shopee-ads và shopee-affiliate. Cấp quyền cả ba trong Kết nối trên
portal, y hệt shopee — nhưng mỗi app tạo một kết nối riêng, tính riêng
vào hạn mức gói dù cùng một shop. Xem Shopee Ads và Shopee
Affiliate.
Xác thực và mã lỗi¶
Giống hệt mọi nền tảng khác: X-API-Key + X-Account-Id (xem Xác
thực), cùng bộ mã lỗi. X-Account-Id ở
đây trỏ tới một shop Shopee.