Tự động hóa Shopee bằng n8n qua API, không cần tự xin app Shopee

Bài toán: vì sao người bán khó dùng n8n với Shopee?

Khó vì Shopee chỉ cấp API cho app đã được duyệt trên Shopee Open Platform. Mỗi lệnh gọi phải ký bằng partner_id, khóa bí mật và token của gian hàng; token hết hạn sau vài giờ phải làm mới. Một shop vừa và nhỏ hiếm khi có người lo phần này.

Kết quả là n8n bị dùng nửa vời. Người ta tải file tay, đẩy lên Drive, rồi để n8n đọc file. Dữ liệu vẫn qua tay người, vẫn trễ một ngày và vẫn có thể bị sửa.

Quantri360 đã có app Shopee được duyệt. Partner cho bạn gọi chính các API đó bằng một API key; 360 lo ký, gắn token và làm mới token.

Tư duy dẫn đường: cần dữ liệu nào, đọc thế nào cho đúng?

Mỗi workflow nên trả lời một câu hỏi quản trị cụ thể, không gom "lấy hết dữ liệu". Đặt câu hỏi trước, rồi mới chọn API.

Ba bẫy đã làm sai số thật:

• Cursor không chạy vẫn trả 200. Ở API thu nhập, next_page là một object { cursor, page_size }. Truyền nguyên object vào tham số thì Shopee trả lại trang đầu, vòng lặp cộng cùng 100 bản ghi nhiều lần. Luôn lấy đúng trường cursor, và khử trùng theo order_sn: trang mới không thêm mã nào thì dừng.
• Lỗi tham số tính vào app, không chỉ vào bạn. Shopee chấm tỉ lệ gọi thành công của app (yêu cầu từ 90% trở lên). Vì vậy 360 kiểm tham số bắt buộc theo danh mục và trả lỗi 400 trước khi gọi Shopee. Đọc kỹ thông báo lỗi thay vì cho workflow thử lại liên tục.
• Đơn hoàn tất chưa chắc đã giao. Đơn giao thất bại vẫn COMPLETED. Workflow cảnh báo phải đọc trạng thái kiện LOGISTICS_DELIVERY_FAILED.

AI bứt tốc: thiết lập trong bao lâu, gồm những bước nào?

Từ lúc có key tới workflow đầu tiên chạy được mất khoảng 20 phút. Mẫu có sẵn làm phần khó nhất: tính cửa sổ thời gian và phân trang.

1. Đăng ký ở Partner Quantri360, bật xác thực hai lớp, ủy quyền gian hàng ở nền tảng Shopee.
2. Tạo API key ở mục Quản lý API. Có thể giới hạn key theo IP hoặc dải IP của máy chủ n8n và đặt hạn dùng. Tạo key là đồng ý điều khoản: key không chia sẻ, dữ liệu chỉ dùng cho gian hàng của chính bạn.
3. Ở mục Tài liệu, tải mẫu workflow n8n cho Shopee rồi nhập vào n8n. Mẫu gồm: lịch 06:00 → tính cửa sổ "hôm qua" theo giờ Việt Nam → HTTP Request gọi get_order_list qua 360, tự lặp cursor tới khi more = false → tách từng đơn.
4. Tạo credential Header Auth: Name Authorization, Value Bearer <key>. Brand nhiều gian hàng thì điền platform_shop_id.
5. Nối node cuối vào việc bạn cần: Google Sheets, Postgres, Telegram, hoặc gọi tiếp get_order_detail.

Lệnh gọi trong node HTTP Request tương đương:

curl -s "https://partner.quantri360.com/v1/shopee/api/v2/order/get_order_detail?order_sn_list=2510190ABCDEF1,2510190ABCDEF2&response_optional_fields=item_list,total_amount" \
  -H "Authorization: Bearer $KEY"

360 trả nguyên phản hồi của Shopee, kèm header X-Q360-Request-Id để tra lỗi. Mã lỗi của 360: 400 reserved_param (bạn gửi token hay chữ ký), 403 endpoint_not_allowed (API chưa mở), 429 hoặc 503 thì chờ theo Retry-After.

Thêm AI vào workflow. Sau node tách đơn, thêm node AI (OpenAI hoặc Anthropic) với lời nhắc cố định:

"Dưới đây là danh sách kiện giao thất bại hôm qua: mã đơn, tỉnh, đơn vị vận chuyển, giá trị. Nhóm theo đơn vị vận chuyển và tỉnh. Viết 3 dòng gửi trưởng kho: nhóm nào bất thường so với tỉ lệ trung bình, cần gọi lại khách nào trước."

Gửi kết quả qua Telegram hoặc email mỗi sáng. AI tóm tắt; người quản lý quyết định gọi ai.

Kết quả đo được

Một workflow tốt phải đo được nó tiết kiệm gì và bắt được gì. Ghi lại bốn số dưới đây trong tháng đầu chạy.

• Giờ công: thời gian tải file, lọc, gửi báo cáo mỗi tuần trước và sau khi có workflow.
• Độ trễ cảnh báo: khoảng cách từ lúc kiện đổi trạng thái tới lúc tin nhắn đến; với lịch hằng ngày là dưới 24 giờ, chạy mỗi giờ thì dưới một giờ.
• Sai lệch bắt được: số đơn trùng do cursor (đếm mã trùng trước khi khử) và số đơn giao thất bại bị tính là hoàn tất.
• Lượt gọi: trang Đo lường của Partner ghi số request trong tháng theo nền tảng và loại dữ liệu, kèm số lần 360 gọi sàn; tăng đột biến là dấu hiệu workflow gọi thừa.

Chưa muốn dựng n8n? Có thể đưa thẳng đơn vào Google Sheets theo lịch. Cần kho dữ liệu để Power BI đọc, xem đổ đơn sàn vào SQL. Lượt gọi tính theo gói, xem bảng giá.

API liên quan

• get_order_list: danh sách đơn theo cửa sổ, nút đầu tiên của hầu hết workflow.
• get_order_detail: sản phẩm, địa chỉ, tổng tiền của tối đa 50 đơn.
• get_package_detail: trạng thái kiện để bắt giao thất bại.
• get_escrow_detail: tiền thực nhận và phí của từng đơn.
• get_wallet_transaction_list: bút toán ví người bán.
• get_income_detail: thu nhập đã và chưa giải ngân, phân trang bằng next_page.cursor.

Đọc thêm: tự động hóa quy trình kinh doanh — bài tổng quan của chủ đề này.