API Docs - Shopee Affiliate Server

🔐 Xác thực (Auth)

POST /api/auth/login Đăng nhập — lấy JWT token

Request Body (JSON)

Tham số	Loại		Mô tả
`password`	string	Required	Mật khẩu đăng nhập

Ví dụ

curl -X POST '${BASE}/api/auth/login' \
  -H 'Content-Type: application/json' \
  -d '{"password":"your-password"}'

Response — không bật 2FA

{
  "ok": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "mfaRequired": false
}

Response — đã bật 2FA

{
  "ok": true,
  "mfaRequired": true,
  "tempToken": "eyJhbGci..."   // dùng để verify-mfa, hết hạn sau 5 phút
}

POST /api/auth/verify-mfa Xác thực mã 2FA → lấy JWT cuối

Request Body (JSON)

Tham số	Loại		Mô tả
`tempToken`	string	Required	Token tạm nhận từ /login (hết hạn 5 phút)
`code`	string	Required	Mã 6 chữ số từ Google Authenticator / Authy

Ví dụ

curl -X POST '${BASE}/api/auth/verify-mfa' \
  -H 'Content-Type: application/json' \
  -d '{"tempToken":"eyJ...","code":"123456"}'

Response

{ "ok": true, "token": "eyJhbGci..." }

GET /api/auth/2fa/setup Auth Lấy QR code để cài 2FA

Chỉ gọi được khi 2FA chưa bật.

Ví dụ

curl '${BASE}/api/auth/2fa/setup' \
  -H 'Authorization: Bearer <TOKEN>'

Response

{
  "ok": true,
  "secret": "BASE32SECRET...",   // lưu lại để enable
  "qrCode": "data:image/png;base64,..."
}

POST /api/auth/2fa/enable Auth Bật 2FA

Request Body (JSON)

Tham số	Loại		Mô tả
`secret`	string	Required	Base32 secret nhận từ /2fa/setup
`code`	string	Required	Mã 6 digits xác nhận

Ví dụ

curl -X POST '${BASE}/api/auth/2fa/enable' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"secret":"BASE32...","code":"123456"}'

Response

{ "ok": true, "message": "2FA enabled" }

POST /api/auth/2fa/disable Auth Tắt 2FA

Request Body (JSON)

Tham số	Loại		Mô tả
`code`	string	Required	Mã 2FA hiện tại để xác nhận

Ví dụ

curl -X POST '${BASE}/api/auth/2fa/disable' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"code":"123456"}'

Response

{ "ok": true, "message": "2FA disabled" }

🍪 Đồng bộ Cookie

Cookie Shopee Affiliate được lưu trên server RAM. Server tự dùng cookie này khi convert nếu client không gửi cookie. Extension Chrome tự động sync, hoặc có thể sync thủ công qua 2 endpoint dưới đây.

POST /api/sync-cookie Extension gửi cookie lên server (không cần auth)

Request Body (JSON)

Tham số	Loại		Mô tả
`cookie`	string	Required	Chuỗi cookie đầy đủ (SPC_EC, SPC_F, SPC_ST, SPC_U, csrftoken...)
`accountName`	string	Optional	Tên tài khoản để nhận biết

Ví dụ

curl -X POST '${BASE}/api/sync-cookie' \
  -H 'Content-Type: application/json' \
  -d '{
    "cookie": "SPC_EC=abc;SPC_F=xyz;csrftoken=tok",
    "accountName": "Tài khoản chính"
  }'

Response

{
  "ok": true,
  "accountName": "Tài khoản chính",
  "syncedAt": "2025-01-01T00:00:00.000Z"
}

POST /api/sync-cookie-local Sync cookie nhanh từ local machine (không cần auth)

Giống /api/sync-cookie, dùng cho sync thủ công từ máy tính cá nhân.

Ví dụ

curl -X POST '${BASE}/api/sync-cookie-local' \
  -H 'Content-Type: application/json' \
  -d '{"cookie":"SPC_EC=...","accountName":"Local"}'

Response

{ "ok": true, "accountName": "Local", "syncedAt": "..." }

GET /api/sync-cookie Lấy trạng thái cookie đang lưu trên server

Response — có cookie

{
  "ok": true,
  "cookie": "SPC_EC=...;SPC_F=...",
  "accountName": "Tài khoản chính",
  "syncedAt": "2025-01-01T07:00:00.000Z"
}

Response — chưa có cookie

{ "ok": false, "error": "Chưa có cookie nào được sync." }

⚡ Convert Link Affiliate

POST /api/convert Auth Convert Shopee links → affiliate links + thông tin sản phẩm

Request Body (JSON)

Tham số	Loại		Mô tả
`links`	string[]	Required	Mảng URL Shopee (tối đa 15 link/request)
`subIds`	string[]	Optional	Sub-ID tracking — tối đa 5 giá trị
`cookie`	string	Optional	Cookie Shopee Affiliate. Nếu bỏ trống → server tự dùng cookie đã sync từ extension

Ví dụ Request

curl -X POST '${BASE}/api/convert' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer eyJhbGci...' \
  -d '{
    "links": [
      "https://shopee.vn/product-name-i.123456.987654",
      "https://s.shopee.vn/AbCdEf"
    ],
    "subIds": ["n8n", "campaign1"]
  }'

Response đầy đủ

{
  "ok": true,
  "mapping": {
    "https://shopee.vn/product-name-i.123456.987654": {
      "shortLink": "https://s.shopee.vn/xXxXxX",   // link affiliate của tài khoản bạn
      "longLink":  "https://affiliate.shopee.vn/...",
      "failCode":  0,
      "product": {
        "name":              "Tên sản phẩm đầy đủ",
        "price":             299000,                  // VNĐ (số nguyên)
        "image":             "https://cf.shopee.vn/file/...",
        "shopName":          "Tên Shop",
        "rating":            "4.8",
        "sales":             1500,                    // số lượng đã bán
        "commission":        53820,                   // HH ước tính tổng (VNĐ)
        "commissionRate":    "18.0%",                 // % HH ước tính
        "sellerCommission":  35880,                   // HH từ seller (VNĐ)
        "shopeeCommission":  17940,                   // HH từ Shopee (VNĐ)
        "isXtra":            true,                    // có Xtra commission
        "cap":               50000,                   // cap HH tối đa (VNĐ)
        "productLink":       "https://shopee.vn/product/..."
      }
    },
    "https://s.shopee.vn/AbCdEf": {
      "error":    true,
      "failCode": 10   // link không hợp lệ hoặc hết hạn
    }
  }
}

Giải thích failCode

failCode	Ý nghĩa
`0`	Thành công
`-1`	Lỗi không xác định
`10`	Link không hợp lệ
`40300`	Cookie hết hạn / không có quyền

Lưu ý

shortLink được tạo bằng cookie tài khoản affiliate của bạn → hoa hồng về tài khoản bạn.
commission / commissionRate là ước tính từ API bên thứ 3 (addlivetag) — tỷ lệ thực nhận phụ thuộc user_rate tài khoản bạn.
Nếu không truyền cookie, server tự dùng cookie đã sync từ extension.

🩺 Health Check

GET /api/health Trạng thái server và Playwright browser

Response

{
  "ok": true,
  "browserReady": true,        // false = Playwright chưa khởi động xong
  "timestamp": "2025-01-01T00:00:00.000Z"
}

🤖 Tích hợp n8n Workflow

Luồng cơ bản (3 node):

HTTP Request — POST /api/auth/login → lưu {{ $json.token }}
HTTP Request — POST /api/convert với header Auth + body links
Code / Set node — xử lý mapping lấy shortLink và thông tin SP

Node 1 — Login:

Method:  POST
URL:     ${BASE}/api/auth/login
Body:    { "password": "your-password" }
→ Lưu output: token = {{ $json.token }}

Node 2 — Convert:

Method:  POST
URL:     ${BASE}/api/convert
Headers: Authorization = Bearer {{ $('Login').item.json.token }}
         Content-Type  = application/json
Body (JSON):
{
  "links": {{ JSON.stringify($json.links) }},
  "subIds": ["n8n"]
}

Node 3 — Lấy kết quả (Code node):

const mapping = $input.item.json.mapping;
const results = [];
for (const [originalUrl, data] of Object.entries(mapping)) {
  if (data.shortLink) {
    results.push({
      original:       originalUrl,
      shortLink:      data.shortLink,
      productName:    data.product?.name,
      price:          data.product?.price,
      commission:     data.product?.commission,
      commissionRate: data.product?.commissionRate,
    });
  }
}
return results.map(r => ({ json: r }));

Lưu ý quan trọng:

Token hết hạn sau 7 ngày — cần login lại hoặc dùng Sub-workflow riêng để renew.
Không cần truyền cookie nếu đã sync từ extension Chrome trước đó.
Rate limit phụ thuộc Shopee Affiliate API — nên batch tối đa 10-15 link/request.

❌ Mã lỗi HTTP

INFO HTTP Error Codes Các mã lỗi trả về

HTTP Code	Ý nghĩa	Xử lý
`400`	Request thiếu/sai tham số	Kiểm tra body request
`401`	Sai password hoặc mã 2FA	Đăng nhập lại
`403`	Token không hợp lệ hoặc hết hạn	Gọi /login lấy token mới
`502`	Playwright lỗi (Shopee API thất bại)	Kiểm tra cookie còn hạn không
`503`	Browser chưa sẵn sàng	Đợi vài giây rồi retry
`500`	Lỗi server nội bộ	Xem log server

Response format lỗi

{ "ok": false, "error": "Mô tả lỗi chi tiết" }

📡 API Documentation