# Hướng dẫn LocLink Affiliate Assistant v3

LocLink Affiliate Assistant là công cụ độc lập hỗ trợ:

- Chuyển link Shopee và Lazada thành link Affiliate.
- Lọc và lưu mã voucher.
- Đọc báo cáo click, đơn hàng, GMV và hoa hồng.

Tool không yêu cầu nhập mật khẩu, không lưu cookie và không gửi session lên Worker.

## Lưu ý khi deploy `loclink.pages.dev`

Bản 3.1.1 không cần Cloudflare Worker cho Lazada. Tool ký request trên trình duyệt và gọi thẳng Lazada Open API; chỉ cần deploy các file tĩnh như `index.html`, `shopee_tool.js` và `shopee_tool.user.js`.

## 1. Cài trên máy tính

1. Mở `https://loclink.pages.dev`.
2. Nhấn **Ctrl + Shift + B** để hiện thanh Dấu trang.
3. Kéo nút **LocLink Assistant** lên thanh Dấu trang.
4. Mở Shopee hoặc Shopee Affiliate bằng trình duyệt.
5. Bấm dấu trang **LocLink Assistant** để mở công cụ.

Nếu không kéo được, bấm **Sao chép mã LocLink**, tạo một dấu trang mới rồi dán mã vào ô **URL/Địa chỉ**.

## 2. Cài trên Android

1. Mở `https://loclink.pages.dev` bằng Chrome.
2. Bấm **Sao chép mã LocLink cho Android**.
3. Trong Chrome, bấm **⋮ → Thêm vào dấu trang** để lưu trang LocLink.
4. Vào **⋮ → Dấu trang**, bấm ⋮ cạnh dấu trang vừa tạo rồi chọn **Chỉnh sửa**.
5. Đổi tên thành **LocLink** và dán mã đã sao chép vào ô URL.
6. Khi đang ở Shopee, chạm thanh địa chỉ, gõ **LocLink** rồi chọn kết quả có biểu tượng dấu trang.

## 3. Cài trên iPhone hoặc iPad

1. Mở `https://loclink.pages.dev` bằng Safari.
2. Bấm **Sao chép mã LocLink cho iPhone**.
3. Trong Safari, mở menu trang và chọn **Thêm dấu trang**.
4. Mở Dấu trang, nhấn giữ dấu trang vừa tạo rồi chọn **Sửa**.
5. Đổi tên thành **LocLink** và dán mã đã sao chép vào ô Địa chỉ.
6. Khi đang ở Shopee bằng Safari, mở Dấu trang và bấm **LocLink**.

## Giới hạn của cách dùng bằng Dấu trang

Cách dùng bằng Dấu trang có các giới hạn:

- Phải bấm lại sau khi tải trang mới.
- SubID không đồng bộ giữa Shopee và Affiliate.
- Khi đổi giữa Shopee và Affiliate, cần dán địa chỉ đã sao chép vào thanh địa chỉ của chính tab hiện tại.
- Bookmarklet tải file JavaScript từ `loclink.pages.dev` khi chạy.

Lấy nút kéo-thả và mã LocLink tại `https://loclink.pages.dev`.

## Chức năng nào chạy ở đâu?

| Chức năng | Domain chạy trực tiếp |
|---|---|
| Chuyển link Shopee | `affiliate.shopee.vn` |
| Chuyển link Lazada | Trang đang mở (qua Lazada Open API đã cài) |
| Lưu voucher | `shopee.vn` |
| Báo cáo | `affiliate.shopee.vn` |

Nếu đang ở sai domain, dùng ô **Sao chép** ngay dưới thông báo, dán địa chỉ vào thanh địa chỉ của chính tab hiện tại rồi bấm lại LocLink. Tool không tự mở tab mới và sẽ giữ tạm nội dung đang nhập tối đa 10 phút.

## Chuyển link

1. Mở tab **Chuyển link** tại trang Affiliate nếu nội dung có link Shopee. Nội dung chỉ có link Lazada có thể xử lý ngay trên trang Shopee đang mở.
2. Dán bài viết hoặc danh sách URL Shopee/Lazada. Tool tự nhận diện từng sàn.
3. Nhập SubID nếu cần. Sub ID này được dùng làm `subId1` cho cả Shopee và Lazada.
4. Bấm **Tạo Custom Link**.
5. Kiểm tra số link thành công/thất bại rồi sao chép kết quả.

Link lỗi được giữ nguyên để không làm hỏng nội dung gốc.

### Cài API Lazada

1. Bấm biểu tượng bánh răng ở góc trên bên phải tool hoặc nút **Cài API** trong thông báo “Mới”.
2. Nhập đủ **LiteApp Key**, **LiteApp Secret** và **User Token** nhận từ Lazada.
3. Bấm **Lưu cài đặt**.
4. Dán nội dung có link `lazada.vn`, `s.lazada.vn`, `c.lazada.vn` hoặc `sl.lazada.vn`, rồi bấm **Tạo Custom Link** như với Shopee.

Thông tin được lưu trên trình duyệt hiện tại. LiteApp Secret chỉ dùng để ký request tại trình duyệt; App Key, User Token và request đã ký được gửi thẳng tới Lazada Open API, không đi qua LocLink. Không cài API trên máy công cộng. Với cách dùng bằng Dấu trang, cấu hình local không tự đồng bộ giữa `shopee.vn` và `affiliate.shopee.vn`.

## Lưu voucher

1. Mở tab **Voucher** tại `shopee.vn`.
2. Dán bài viết hoặc danh sách mã.
3. Kiểm tra số mã tool tìm thấy.
4. Bấm **Lưu voucher vào ví**.

Tool gửi lần lượt tối đa 30 mã mỗi lượt. Queue sẽ dừng nếu phát hiện hết phiên đăng nhập hoặc Shopee giới hạn tốc độ.

Nếu đang ở trang Affiliate, tool hiển thị ô sao chép nhanh `shopee.vn`. Sau đó:

1. Bấm **Sao chép** cạnh `shopee.vn`.
2. Dán vào thanh địa chỉ của chính tab hiện tại.
3. Bấm dấu trang **LocLink Assistant**.
4. Nội dung được khôi phục; bấm **Lưu voucher vào ví**.

## Báo cáo

1. Mở tab **Báo cáo** tại trang Affiliate.
2. Chọn khoảng thời gian.
3. Bấm **Tải báo cáo** để công cụ lấy dữ liệu và dựng danh sách Sub ID có sẵn.
4. Mở **Lọc theo Sub ID**, sau đó chọn một tổ hợp trong danh sách. Ô nhập phía trên chỉ dùng để tìm nhanh, không tạo Sub ID mới.

Sau khi dữ liệu đã tải, thay đổi Sub ID sẽ lọc nhanh hoa hồng, GMV và đơn hàng ngay trên trình duyệt. Chọn **Không gắn Sub ID** để xem các chuyển đổi không có Sub ID. Hãy bấm **Tải báo cáo** lần nữa để cập nhật chính xác lượt click theo Sub ID mới.

Quy ước khoảng thời gian:

- Hôm nay: 00:00 đến thời điểm hiện tại.
- Hôm qua: trọn ngày hôm qua.
- 7 ngày: bảy ngày hoàn chỉnh, kết thúc hôm qua.
- 30 ngày: ba mươi ngày hoàn chỉnh, kết thúc hôm qua.

Doanh số hợp lệ (GMV) là tổng `actual_amount` của các sản phẩm thuộc đơn không bị hủy/hoàn. Đơn hủy/hoàn được tách khỏi số đơn, GMV và hoa hồng hợp lệ. Trước khi tải, dashboard hiển thị “—” thay vì số 0.

## Xử lý lỗi

### Công cụ báo cần đăng nhập lại

Mở trực tiếp domain đang dùng, đăng nhập lại rồi chạy tác vụ lần nữa.

### Không đọc được bộ nhớ tạm

Nhấn giữ hoặc dùng `Ctrl + V` trong ô nhập. Trình duyệt có thể chặn Clipboard API trên một số trang.

### Shopee thay đổi cấu trúc báo cáo

Tool sẽ từ chối hiển thị tổng thay vì trả toàn bộ số 0. Cần cập nhật adapter bằng response đã xóa cookie, token, mã đơn và dữ liệu cá nhân.

### Nút nổi đi sai vị trí

Kéo nút sang cạnh trái/phải. Vị trí được tự động clamp trong viewport và lưu cho lần sau.

## Lưu ý

Đây là công cụ độc lập, không phải sản phẩm chính thức hoặc được Shopee bảo trợ. API nội bộ có thể thay đổi mà không báo trước.