Kênh Shopee

Hướng dẫn cấu hình đối tác, ủy quyền OAuth và quản lý gian hàng Shopee Seller trên hệ thống OVIRO.

Tích hợp Shopee cho phép kết nối trực tiếp gian hàng Shopee Seller với OVIRO, hỗ trợ đồng bộ dữ liệu đơn hàng, sản phẩm, tồn kho và trạng thái giao hàng tự động.

Cơ chế kết nối

Shopee sử dụng giao thức OAuth 2.0 của Shopee Open Platform:

Hệ thống OVIRO gọi API tạo URL xác thực có kèm chữ ký bảo mật HMAC-SHA256.
Mở cửa sổ popup để chủ shop đăng nhập tài khoản người bán Shopee và xác nhận cấp quyền cho ứng dụng OVIRO.
Sau khi được cấp quyền, Shopee trả về code và shop_id qua đường dẫn Callback URL để OVIRO đổi lấy Access Token dài hạn.

Quy trình kết nối kênh Shopee

Bước 1: Khai báo thông tin Shopee Open Platform

Trước khi tiến hành thêm kênh, vào Cấu hình bán hàng đa kênh (#/setting/omnichannel/tab/general) và điền thông số tại khối Tích hợp Shopee Seller:

Partner ID: Mã số đối tác đăng ký trên cổng Shopee Open Platform.
Partner Key: Mã khóa bí mật của ứng dụng đối tác.
Môi trường (Sandbox):
- Chọn Production nếu kết nối gian hàng thực tế đang kinh doanh.
- Chọn Sandbox nếu đang trong giai đoạn kiểm thử kỹ thuật với tài khoản test.
Callback URL (Redirect URI): Khai báo đúng đường dẫn nhận mã ủy quyền (ví dụ: https://app.yourdomain.com/v1/ecomchannels/oauth/callback). Đường dẫn này phải được thêm vào mục Redirect URL trong cài đặt ứng dụng trên Shopee Open Platform.
Nhấn Lưu cài đặt.

Bước 2: Thêm kênh và Ủy quyền gian hàng

Vào menu Bán hàng đa kênh > Tích hợp đa kênh.
Nhấn nút Thêm kênh.
Chọn biểu tượng Shopee.
Cửa sổ ủy quyền của Shopee Open Platform xuất hiện:
- Chọn quốc gia/vùng lãnh thổ (ví dụ: Việt Nam).
- Đăng nhập tài khoản Shopee Seller của gian hàng cần liên kết.
- Kiểm tra tên ứng dụng OVIRO và danh sách quyền hạn.
- Nhấn Confirm Authorization (Xác nhận ủy quyền).
Hệ thống hoàn tất kết nối, đóng popup và hiển thị gian hàng Shopee mới trong danh sách kênh với trạng thái Có hiệu lực.

Bước 3: Cài đặt tính năng cho gian hàng Shopee

Sau khi kết nối, nhấn Sửa tại dòng gian hàng Shopee để vào màn hình cấu hình chi tiết:

Màn hình cấu hình chi tiết kênh Shopee trong OVIRO

Kho mặc định: Kho hàng trong OVIRO dùng để xuất kho khi Shopee phát sinh đơn mới.
Lưu đơn hàng vào cửa hàng: Chọn chi nhánh quản lý doanh thu đơn Shopee.
Xử lý khi nhận webhook: Bật tính năng để đơn hàng mới tự động ghi nhận vào OVIRO mà không cần bấm kéo đơn thủ công.
Mapping sản phẩm: Vào tab Mapping sản phẩm để liên kết mã hàng hóa Shopee với SKU trong hệ thống OVIRO.

Quản lý và Kết nối lại

Gia hạn token: Mã Access Token của Shopee có hiệu lực trong 4 giờ và được hệ thống tự động làm mới bằng Refresh Token. Refresh Token có hiệu lực tối đa 1 năm.
Nút Kết nối lại: Khi Refresh Token hết hạn hoặc gian hàng Shopee bị đổi mật khẩu/thu hồi ủy quyền, dòng kênh sẽ chuyển sang trạng thái cảnh báo. Nhấn nút Kết nối lại để đăng nhập và cấp lại quyền cho gian hàng một cách nhanh chóng.

Xử lý sự cố thường gặp

Sự cố	Nguyên nhân	Giải pháp
Thông báo lỗi `error_oauth_url_failed`	Chưa điền Partner ID hoặc Partner Key	Kiểm tra và lưu thông tin tại Cấu hình bán hàng đa kênh.
Shopee báo lỗi "Redirect URL mismatch"	Callback URL trên Shopee Open Platform không khớp với OVIRO	Copy chính xác Callback URL từ OVIRO và dán vào mục App Setting trên Shopee Open Platform.
Đơn hàng không đồng bộ về kho OVIRO	Chưa chọn Kho mặc định trong kênh	Vào chi tiết kênh Shopee > Chọn Kho mặc định trong phần Cấu hình nhận & tạo đơn hàng.
Đang chọn Sandbox nhưng lại đăng nhập tài khoản thật	Lệch môi trường kiểm thử và thực tế	Chuyển tùy chọn Môi trường thành Production tại trang Cấu hình bán hàng đa kênh.