Shopee

Hướng dẫn kết nối, 6 bước

Làm theo thứ tự từ trên xuống. Mỗi bước có ngữ cảnh để đội kỹ thuật của bạn hiểu lý do, không phải checklist bấm.

1. 1

   Đăng ký Shopee Partner

   Vào open.shopee.com, đăng ký tài khoản Partner với mã số thuế và thông tin doanh nghiệp. Phê duyệt mất 3-7 ngày làm việc.

2. 2

   Tạo App trong Partner Console

   Vào mục App, tạo App mới với region Vietnam. Chọn scope: Order Management, Product Management, Payment, Finance, Logistics.

3. 3

   Lấy Partner ID + Partner Key

   Sau khi App được duyệt, copy Partner ID và Partner Key từ trang chi tiết App. Lưu vào vault hoặc env, không hardcode trong code.

4. 4

   Authorize shop của khách hàng

   Gửi link OAuth authorization cho admin của shop để cấp quyền. Sau khi accept, hệ thống nhận được shop_id + access_token + refresh_token.

5. 5

   Triển khai job refresh token tự động

   Access token chỉ tồn tại 4 tiếng. Refresh token tồn tại 30 ngày. Cron job refresh access token mỗi 3 tiếng và refresh refresh token mỗi 25 ngày để tránh hết hạn.

6. 6

   Kết nối các endpoint cốt lõi

   /api/v2/order/get_order_list, /api/v2/product/get_item_list, /api/v2/payment/get_escrow_detail, /api/v2/logistics/get_shipping_parameter. Pull theo cửa sổ 15 ngày, đẩy về data warehouse.

Lỗi và pitfalls thường gặp tại Việt Nam

Đọc kỹ trước khi cam kết timeline, vài rủi ro dưới đây có thể kéo dài tích hợp thêm 1-2 tuần nếu không lên kế hoạch.

• Rate limit: tối đa 1.000 request/phút mỗi Partner ID, cần queue khi pull lịch sử lớn.
• Webhook đơn hàng có thể miss 1-2% trong giờ cao điểm, luôn cần job đối soát theo cửa sổ thời gian.
• Phí sàn (escrow) chỉ trả về sau khi đơn ship xong, cần phân biệt doanh thu gross và net khi báo cáo.
• Khi shop có nhiều chương trình cùng lúc (Voucher + Free Ship + Coin), phí trả về có thể có lệch nhỏ với báo cáo Seller Center, tin báo cáo escrow là nguồn cuối cùng.
• Sandbox và production có endpoint khác nhau, test kỹ trước khi switch sang production.