# API bên thứ 3 & Dịch vụ bên ngoài

Tài liệu chi tiết tất cả các API bên thứ 3 và dịch vụ bên ngoài được sử dụng trong AutoShopee Kit.

---

## Shopee API

Shopee API được chia thành 3 nhóm chính: **Client API** (phía người mua), **Seller API** (phía người bán), và **Affiliate API** (tiếp thị liên kết).

### Cấu hình kết nối

| Tên | Domain | File cấu hình |
|-----|--------|---------------|
| Client | `https://shopee.vn` | `src/app/api/shopee/client/init.js` |
| Seller | `https://banhang.shopee.vn` | `src/app/api/shopee/seller/init.js` |
| Affiliate | `https://open-api.affiliate.shopee.vn/graphql` | `src/app/api/shopee/affiliate.js` |
| Image CDN | `https://cf.shopee.vn/file` | `src/app/config/api.js` |
| Video CDN | `https://cvf.shopee.vn/file` | `src/app/config/api.js` |
| Chat WebSocket | `wss://seller-push-ws.shopee.vn` | `src/app/api/shopee/seller/chat/socket.js` |

### Client API (shopee.vn)

API phía người mua, dùng để lấy thông tin sản phẩm, shop, tìm kiếm, danh mục.

#### Sản phẩm

| Hàm | Method | Endpoint | Mô tả |
|-----|--------|----------|-------|
| `getShopeeProductId` | GET | `/api/v4/pdp/get_pc` | Lấy chi tiết sản phẩm theo product_id + shop_id |
| `fetchShopeeProductStock` | POST | `/api/v4/pdp/cart_panel/select_variation_pc` | Lấy thông tin tồn kho theo phân loại sản phẩm |
| `getShopeeProductListReview` | GET | `/api/v2/item/get_ratings` | Lấy danh sách đánh giá sản phẩm |

**File:** `src/app/api/shopee/client/product/get.js`, `src/app/api/shopee/client/product/index.js`

#### Shop

| Hàm | Method | Endpoint | Mô tả |
|-----|--------|----------|-------|
| `getShopeeShopId` | GET | `/api/v4/shop/get_shop_base` | Lấy thông tin shop theo shopId |
| `getShopeeShopByUsername` | GET | `/api/v4/shop/get_shop_base` | Lấy thông tin shop theo username |
| `shopeeSearchShopId` | GET | `/api/v4/shop/rcmd_items` | Lấy danh sách sản phẩm trong shop |
| `getShopeeProfileClient` | GET | `/api/v2/user/profile/get/` | Lấy thông tin profile người dùng đang đăng nhập |

**File:** `src/app/api/shopee/client/shop/get.js`, `src/app/api/shopee/client/shop/user.js`, `src/app/api/shopee/client/shop/search.js`, `src/app/api/shopee/client/shop/index.js`

#### Tìm kiếm

| Hàm | Method | Endpoint | Mô tả |
|-----|--------|----------|-------|
| `getSearchKeywordProduct` | GET | `/api/v4/search/search_items` | Tìm kiếm sản phẩm theo từ khóa |
| `shopeeSearchProductCategoryId` | GET | `/api/v4/search/search_items` | Tìm kiếm sản phẩm theo danh mục |
| `shopeeSearchProductKeyword` | GET | `/api/v4/search/search_items` | Tìm kiếm sản phẩm theo keyword (wrapper) |
| `shopeeSearchSoldoutShopId` | GET | `/api/v4/search/search_items` | Tìm sản phẩm hết hàng trong shop |

**File:** `src/app/api/shopee/client/search/index.js`, `src/app/api/shopee/client/product/index.js`

#### Thị trường & Từ khóa

| Hàm | Method | Endpoint | Mô tả |
|-----|--------|----------|-------|
| `getKeywordHint` | GET | `/api/v4/search/search_hint` | Gợi ý từ khóa tìm kiếm |
| `getKeywordTrending` | GET | `/api/v4/search/trending_search` | Từ khóa xu hướng |
| `getKeywordSuggest` | GET | `/api/v4/search/search_suggestion` | Gợi ý từ khóa |
| `getShopMallCategoryId` | GET | `/api/v4/official_shop/get_shops` | Lấy danh sách shop mall theo danh mục |
| `getListShopCategoryId` | GET | `/api/v4/official_shop/get_shops` | Lấy danh sách shop top theo danh mục |

**File:** `src/app/api/shopee/client/market/index.js`, `src/app/api/shopee/client/category/index.js`

### Seller API (banhang.shopee.vn)

API phía người bán, yêu cầu xác thực qua cookie `SPC_CDS`. Mỗi request tự động gắn `version`, `SPC_CDS`, `SPC_CDS_VER` qua interceptor.

#### Xác thực & Thông tin shop

| Hàm | Method | Endpoint | Mô tả |
|-----|--------|----------|-------|
| `getShopeeSellerInfo` | GET | `/api/forward/accountservice/v2/shop/` | Lấy thông tin seller cơ bản |
| `getShopeeSellerAccountInfo` | GET | `/api/selleraccount/shop_info/` | Lấy thông tin tài khoản seller |
| `getShopeeSellerFrameworkInfo` | GET | `/api/framework/selleraccount/shop_info/` | Lấy thông tin seller (framework endpoint) |
| `getShopeeSellerLogin` | GET | `/api/v2/login/` | Kiểm tra trạng thái đăng nhập seller |
| `getShopeeSellerConfig` | GET | `/api/sellermisc/sc_conf/get_shop_settings/` | Lấy cấu hình shop |
| `getShopeeWebchatLogin` | POST | `/webchat/api/coreapi/v1.2/mini/login/sc` | Đăng nhập webchat |

**File:** `src/app/api/shopee/seller/get.js`, `src/app/api/shopee/seller/index.js`

#### Tài khoản phụ (Sub-account)

| Hàm | Method | Endpoint | Mô tả |
|-----|--------|----------|-------|
| `getShopeeSubAccountInfo` | GET | `/api/selleraccount/subaccount/get/` | Lấy thông tin tài khoản phụ |
| `getShopeeSubAccountFramework` | GET | `/api/framework/selleraccount/subaccount/get/` | Lấy thông tin tài khoản phụ (framework) |
| `getShopeeSubAccountShopList` | GET | `/api/selleraccount/subaccount/get_shop_list/` | Lấy danh sách shop của tài khoản phụ |

**File:** `src/app/api/shopee/seller/subaccount.js`

#### Sản phẩm

| Hàm | Method | Endpoint | Mô tả |
|-----|--------|----------|-------|
| `getShopeeSellerProductId` | GET | `/api/v3/product/get_product_info` | Lấy chi tiết sản phẩm theo ID |
| `getShopeeAttributeCategoryId` | GET | `/api/v3/category/get_attribute_tree/` | Lấy thuộc tính danh mục |
| `shopeeSellerSearchProductList` | GET | `/api/v3/mpsku/list/search_product_list` | Tìm kiếm sản phẩm seller |
| `shopeeSellerUpdateProductId` | POST | `/api/v3/product/update_product_info/` | Cập nhật thông tin sản phẩm |
| `shopeeSellerCreateProduct` | POST | `/api/v3/product/create_product_info` | Tạo sản phẩm mới |
| `getShopeSellerWarehouseList` | GET | `/api/v3/product/get_shop_warehouse/` | Lấy danh sách kho hàng |
| `uploadImageBloob` | POST | `api/v3/general/upload_image/` | Upload hình ảnh sản phẩm |

**File:** `src/app/api/shopee/seller/product/get.js`, `src/app/api/shopee/seller/product/list.js`, `src/app/api/shopee/seller/product/post.js`, `src/app/api/shopee/image.js`

#### Đơn hàng

| Hàm | Method | Endpoint | Mô tả |
|-----|--------|----------|-------|
| `getOrderId` | GET | `/api/v3/order/get_one_order` | Lấy chi tiết một đơn hàng |
| `getOrderStats` | GET | `/api/sellermisc/homepage/get_to_do_list_summary/` | Lấy thống kê tổng quan đơn hàng |
| `getListOrderIndex` | POST | `/api/v3/order/search_order_list_index` | Tìm kiếm danh sách đơn hàng (index) |
| `getListOrderCard` | POST | `/api/v3/order/get_order_list_card_list` | Lấy thông tin card đơn hàng |
| `getListOrderButton` | POST | `/api/v3/order/get_order_list_buttons` | Lấy nút thao tác đơn hàng |
| `ratingOrderCompleted` | POST | `/api/v3/order/rate_order/` | Đánh giá đơn hàng đã hoàn thành |

**File:** `src/app/api/shopee/seller/order/index.js`, `src/app/api/shopee/seller/order/list.js`, `src/app/api/shopee/seller/order/post.js`

#### In đơn hàng

| Hàm | Method | Endpoint | Mô tả |
|-----|--------|----------|-------|
| `getShopeePrintPdf` | GET | `/api/v3/logistics/download_sd_job` | Tải file PDF phiếu vận chuyển |
| `getShopeSellerLogisticList` | GET | `/api/v3/logistics/get_channel_list/` | Lấy danh sách kênh vận chuyển |

**File:** `src/app/api/shopee/seller/order/print.js`, `src/app/api/shopee/seller/index.js`

#### Flash Sale

| Hàm | Method | Endpoint | Mô tả |
|-----|--------|----------|-------|
| `getTimeSlotFlashSale` | GET | `/api/marketing/v4/shop_flash_sale/time_slot/` | Lấy khung giờ flash sale |
| `createFlashSaleIdFromTime` | POST | `/api/marketing/v4/shop_flash_sale/set/` | Tạo flash sale từ khung giờ |
| `removeFlashSaleId` | POST | `/api/marketing/v4/shop_flash_sale/set/` | Xóa flash sale |
| `updateFlashSaleSetListProduct` | POST | `/api/marketing/v4/shop_flash_sale/batch_items/set/` | Thêm sản phẩm vào flash sale |
| `updateFlashSaleIndexListProduct` | POST | `/api/marketing/v4/shop_flash_sale/item_seq/` | Sắp xếp thứ tự sản phẩm flash sale |
| `getListFlashSale` | GET | `/api/marketing/v4/shop_flash_sale/list/` | Danh sách flash sale |
| `getFlashSaleId` | GET | `/api/marketing/v4/shop_flash_sale/batch_items/get` | Chi tiết sản phẩm trong flash sale |
| `getFlashSaleCampaignId` | GET | `/api/marketing/v4/shop_flash_sale/get/` | Chi tiết chiến dịch flash sale |
| `getFlashSaleReport` | GET | `/api/mydata/v2/marketing/flash-sale/overview/` | Báo cáo hiệu quả flash sale |
| `getProductListFlashSale` | GET | `/api/marketing/v4/public/product_selector/` | Danh sách sản phẩm cho flash sale |

**File:** `src/app/api/shopee/seller/flashsale.js`

#### Quảng cáo (Ads)

| Hàm | Method | Endpoint | Mô tả |
|-----|--------|----------|-------|
| `getListAdsCampaign` | GET | `/api/marketing/v3/pas/homepage/` | Danh sách chiến dịch quảng cáo |
| `getAdsCampaignId` | GET | `/api/marketing/v3/pas/campaign/` | Chi tiết chiến dịch quảng cáo |
| `addKeywordCampaignId` | PUT | `/api/marketing/v3/pas/search/` | Thêm từ khóa vào chiến dịch |
| `updateKeywordCampaignId` | PUT | `/api/marketing/v3/pas/search/` | Cập nhật từ khóa chiến dịch |

**File:** `src/app/api/shopee/seller/ads.js`

#### Marketing & Voucher

| Hàm | Method | Endpoint | Mô tả |
|-----|--------|----------|-------|
| `getListVoucherAll` | GET | `/api/marketing/v3/voucher/list/` | Danh sách voucher |
| `getListVoucherActive` | GET | `/api/marketing/v3/voucher/list/` | Danh sách voucher đang hoạt động |

**File:** `src/app/api/shopee/seller/marketing.js`

#### Đánh giá (Rating)

| Hàm | Method | Endpoint | Mô tả |
|-----|--------|----------|-------|
| `getRatingListUnReply` | GET | `/api/v3/settings/search_shop_rating_comments_new/` | Danh sách đánh giá chưa trả lời |
| `getRatingListReply` | GET | `/api/v3/settings/search_shop_rating_comments_new/` | Danh sách đánh giá (có bộ lọc) |
| `getRatingMeta` | GET | `/api/v3/settings/search_shop_rating_comments_new/` | Thống kê đánh giá |
| `replyRatingId` | POST | `/api/v3/settings/reply_shop_rating/` | Trả lời đánh giá |

**File:** `src/app/api/shopee/seller/rating.js`

#### Chat / Tin nhắn

| Hàm | Method | Endpoint | Mô tả |
|-----|--------|----------|-------|
| `sendChatMessage` | POST | `/webchat/api/v1.2/mini/messages` | Gửi tin nhắn (text, sticker, image, product, voucher) |
| `uploadImageWebchat` | POST | `/webchat/api/coreapi/v1.2/images` | Upload hình ảnh trong chat |
| `updateConversationStatus` | PUT | `/webchat/api/v1.2/mini/conversations/:id/status` | Cập nhật trạng thái hội thoại (active/closed) |
| `getConversationRedirection` | POST | `/webchat/api/v1.2/mini/conversation/redirection` | Lấy thông tin chuyển hướng hội thoại |

**File:** `src/app/api/shopee/seller/chat/index.js`

#### Chat WebSocket

| URL | Mô tả |
|-----|-------|
| `wss://seller-push-ws.shopee.vn/socket.io/?region=vn&EIO=3&transport=websocket` | WebSocket nhận tin nhắn chat real-time |

Events:

- `login` - Xác thực kết nối
- `heartbeat` - Giữ kết nối
- `message` - Nhận tin nhắn mới

**File:** `src/app/api/shopee/seller/chat/socket.js`

### Affiliate API (GraphQL)

| Hàm | Method | Endpoint | Mô tả |
|-----|--------|----------|-------|
| `getShortLink` | POST (GraphQL) | `/` (baseURL: `https://open-api.affiliate.shopee.vn/graphql`) | Tạo link rút gọn affiliate |

Sử dụng xác thực SHA256 signature: `SHA256 Credential={appId}, Timestamp={timestamp}, Signature={signature}`

**File:** `src/app/api/shopee/affiliate.js`

---

## TikTok Shop API

### Cấu hình kết nối

| Tên | Domain | File cấu hình |
|-----|--------|---------------|
| Client (Shop) | `https://shop-vn.tiktok.com` | `src/app/api/tiktok/client/init.js` |
| Seller | `https://seller-vn.tiktok.com` | `src/app/api/tiktok/seller/init.js` |

### Client API (shop-vn.tiktok.com)

| Hàm | Method | Endpoint | Mô tả |
|-----|--------|----------|-------|
| `tiktokSearchListProductCategoryId` | POST | `/api/shop/home/product_list` | Tìm kiếm sản phẩm theo danh mục |
| `getTiktokProductId` | GET | `/pdp/{productId}?__loader=(shop$)/(pdp)/(name$)/(id)/page` | Lấy chi tiết sản phẩm |

**File:** `src/app/api/tiktok/client/category.js`, `src/app/api/tiktok/client/product.js`

### Seller API (seller-vn.tiktok.com)

| Hàm | Method | Endpoint | Mô tả |
|-----|--------|----------|-------|
| `getTiktokSellerInfo` | GET | `/api/v1/seller/common/get` | Lấy thông tin seller |

**File:** `src/app/api/tiktok/seller/get.js`

### TikTok qua AutoShopee Backend

Các thao tác nâng cao với TikTok Shop được xử lý qua AutoShopee backend API:

| Hàm | Method | Endpoint | Mô tả |
|-----|--------|----------|-------|
| `getListShop` | GET | `/tiktok/shop/list` | Danh sách shop TikTok đã kết nối |
| `refreshToken` | GET | `/tiktok/shop/refresh/:id` | Làm mới token shop |
| `getShopWarehouse` | GET | `/tiktok/handler/warehouse/:id` | Lấy danh sách kho hàng |
| `importProduct` | POST | `/tiktok/product/import` | Import sản phẩm vào hệ thống |
| `saveUpload` | POST | `/tiktok/upload/single/save` | Lưu sản phẩm chuẩn bị upload |
| `handlerUpload` | POST | `/tiktok/upload/product/run/:id` | Thực thi upload sản phẩm lên TikTok |

**File:** `src/app/api/autoshopee/tiktok/index.js`

---

## Lazada API

### Cấu hình kết nối

| Tên | Domain | File cấu hình |
|-----|--------|---------------|
| Client | `https://lazada.vn` | `src/app/api/lazada/client/init.js` |
| Seller | `https://sellercenter.lazada.vn` | `src/app/api/lazada/seller/init.js` |

### Seller API (sellercenter.lazada.vn)

| Hàm | Method | Endpoint | Mô tả |
|-----|--------|----------|-------|
| `getLazadaSellerInfo` | GET | `/site/globalData` | Lấy thông tin seller Lazada |

**File:** `src/app/api/lazada/seller/get.js`

### Lazada qua AutoShopee Backend

| Hàm | Method | Endpoint | Mô tả |
|-----|--------|----------|-------|
| `getListShop` | GET | `/lazada/shop/list` | Danh sách shop Lazada đã kết nối |
| `refreshToken` | GET | `/lazada/shop/refresh/:id` | Làm mới token shop |
| `importProduct` | POST | `/lazada/product/import` | Import sản phẩm vào hệ thống |
| `saveUpload` | POST | `/lazada/upload/single/save` | Lưu sản phẩm chuẩn bị upload |
| `handlerUpload` | POST | `/lazada/upload/product/run/:id` | Thực thi upload sản phẩm lên Lazada |

**File:** `src/app/api/autoshopee/lazada/index.js`

---

## AI / GPT API

### Cấu hình kết nối

| Tên | Base URL | Timeout |
|-----|----------|---------|
| GPT API | `https://gpt-api.autoshopee.com/api` | 60000ms |

GPT API là proxy nội bộ AutoShopee, kết nối với dịch vụ AI phía backend để sinh nội dung tự động.

### Endpoints

| Hàm | Method | Endpoint | Mô tả |
|-----|--------|----------|-------|
| `gptWriteContent` | POST | `/writer/title` | Viết lại/cải thiện nội dung tiêu đề chung |
| `gptWriterProductTitle` | POST | `/shopee/product/writer/title` | Sinh tiêu đề sản phẩm Shopee tối ưu SEO |
| `gptWriterProductDescription` | POST | `/shopee/product/writer/description` | Sinh mô tả sản phẩm Shopee chi tiết |

**Payload:** `{ text: string }` - Văn bản gốc cần xử lý

**Response:** `{ data: { content: string } }` - Nội dung đã được AI viết lại

**Fallback:** Nếu API lỗi, trả về text gốc không thay đổi.

**File:** `src/app/api/gpt.js`

---

## Các dịch vụ AutoShopee nội bộ

Các service nội bộ AutoShopee hoạt động như middleware/proxy cho extension.

### AutoShopee Main API

**Base URL:** `{VITE_API_URL}/api/v1`

#### Xác thực & User

| Hàm | Method | Endpoint | Mô tả |
|-----|--------|----------|-------|
| `loginUser` | POST | `/extension/login` | Đăng nhập extension |
| `getUserInfo` | GET | `/extension/user/get/me` | Lấy thông tin user hiện tại |
| `checkProfileId` | GET | `/extension/user/profile/check` | Kiểm tra profile ID |

**File:** `src/app/api/autoshopee/user.js`

#### Database (CouchDB)

| Hàm | Method | Endpoint | Mô tả |
|-----|--------|----------|-------|
| `getCouchDatabase` | POST | `/extension/db/get` | Lấy thông tin kết nối CouchDB |
| `createCouchDatabase` | POST | `/extension/db/create` | Tạo database CouchDB mới |

**File:** `src/app/api/autoshopee/db.js`

#### Shopee Shop Management

| Hàm | Method | Endpoint | Mô tả |
|-----|--------|----------|-------|
| `shopeeShopSyncSellerCreate` | POST | `/shopee/shop/create` | Tạo shop seller mới |
| `shopeeShopSync` | POST | `/extension/shopee/shop/sync` | Đồng bộ thông tin shop |
| `shopeeShopCreate` | POST | `/extension/shopee/shop/create` | Tạo shop mới |
| `shopeeShopGetShopId` | GET | `/extension/shopee/shop/get` | Lấy thông tin shop theo shopId |
| `shopeeShopUpdateShopId` | POST | `/extension/shopee/shop/update/:shopId` | Cập nhật thông tin shop |
| `shopeeShopRemoveShopId` | POST | `/extension/shopee/shop/remove/:shopId` | Xóa shop |
| `shopeeShopSyncFromBackground` | POST | `/extension/shopee/syncData` | Đồng bộ dữ liệu từ background |

**File:** `src/app/api/autoshopee/shopee/shop.js`

#### Shopee Ads Keyword Collection

| Hàm | Method | Endpoint | Mô tả |
|-----|--------|----------|-------|
| `apiCollectionCreate` | POST | `/extension/shopee/ads/keyword/create` | Tạo bộ sưu tập từ khóa |
| `apiCollectionList` | GET | `/extension/shopee/ads/keyword/list` | Danh sách bộ sưu tập |
| `apiCollectionRemove` | POST | `/extension/shopee/ads/keyword/remove/:id` | Xóa bộ sưu tập |
| `apiCollectionUpdate` | POST | `/extension/shopee/ads/keyword/update/:id` | Cập nhật bộ sưu tập |
| `apiKeywordList` | GET | `/extension/shopee/ads/keyword/item/list/:collectionId` | Danh sách từ khóa trong bộ sưu tập |
| `apiKeywordAdd` | POST | `/extension/shopee/ads/keyword/item/add/:collectionId` | Thêm từ khóa |
| `apiKeywordRemove` | POST | `/extension/shopee/ads/keyword/item/remove/:id` | Xóa từ khóa |
| `apiKeywordUpdate` | POST | `/extension/shopee/ads/keyword/item/update/:id` | Cập nhật từ khóa |

**File:** `src/app/api/autoshopee/shopee/keyword.js`

#### Shopee Flash Sale Scheduler

| Hàm | Method | Endpoint | Mô tả |
|-----|--------|----------|-------|
| `apiFlashsaleSchedulerList` | GET | `/extension/shopee/flashsale/scheduler/list` | Danh sách lịch flash sale |
| `apiFlashsaleSchedulerSlot` | GET | `/extension/shopee/flashsale/scheduler/slot` | Danh sách slot flash sale |
| `apiFlashsaleSchedulerGetId` | GET | `/extension/shopee/flashsale/scheduler/get/:refId` | Chi tiết lịch flash sale |
| `apiFlashsaleSchedulerCreate` | POST | `/extension/shopee/flashsale/scheduler/create` | Tạo lịch flash sale |
| `apiFlashsaleSchedulerRemove` | POST | `/extension/shopee/flashsale/scheduler/remove/:removeId` | Xóa lịch flash sale |
| `apiFlashsaleSchedulerSetId` | POST | `/extension/shopee/flashsale/scheduler/set/:setId` | Gán flashsaleId cho lịch |
| `apiFlashsaleCampaignList` | GET | `/extension/shopee/flashsale/campaign/list` | Danh sách chiến dịch flash sale |
| `apiFlashsaleCampaignCreate` | POST | `/extension/shopee/flashsale/campaign/create` | Tạo chiến dịch flash sale |
| `apiFlashsaleCampaignUpdate` | POST | `/extension/shopee/flashsale/campaign/update/:updateId` | Cập nhật chiến dịch |
| `apiFlashsaleCampaignRemove` | POST | `/extension/shopee/flashsale/campaign/remove/:removeId` | Xóa chiến dịch |
| `apiFlashsaleCampaignGetId` | GET | `/extension/shopee/flashsale/campaign/get/:campaignId` | Chi tiết chiến dịch |

**File:** `src/app/api/autoshopee/shopee/flashsale.js`

#### Public API (không cần xác thực)

| Hàm | Method | Endpoint | Mô tả |
|-----|--------|----------|-------|
| `getAffLink` | GET | `/public/tracking/get` | Lấy link affiliate tracking |
| `downloadVideoShopee` | POST | `/public/shopee/product/downloadVideo` | Tải video sản phẩm Shopee |
| `getShopeeProductExtraInfo` | GET | `/public/shopee/productSync/data` | Lấy dữ liệu bổ sung sản phẩm (SKU, tồn kho, kích thước) |

**File:** `src/app/api/autoshopee/public.js`

### AutoShopee CMS

**Base URL:** `{VITE_CMS_URL}`

| Hàm | Method | Endpoint | Mô tả |
|-----|--------|----------|-------|
| `fetchListEcosystem` | GET | `/ecosystems` | Danh sách hệ sinh thái |
| `fetchExtensionInfo` | GET | `/extension` | Thông tin extension (version, changelog) |
| `fetchPlatformConfig` | GET | `/platform-config` | Cấu hình nền tảng |

**File:** `src/app/api/autoshopee/cms.js`

### PDF Service

**Base URL:** `https://service-3rd.autoshopee.com`

Dịch vụ xử lý file PDF (chuyển đổi, trích xuất thông tin).

| Hàm | Method | Endpoint | Mô tả |
|-----|--------|----------|-------|
| `parsePdfToHtml` | POST | `/pdftohtml` | Chuyển PDF sang HTML |
| `parsePdfToText` | POST | `/pdftotext` | Chuyển PDF sang văn bản thuần |
| `parsePdfInfo` | POST | `/pdfinfo` | Trích xuất metadata PDF |
| `parsePdfData` | POST | (tổng hợp) | Chuyển PDF sang HTML + text + đếm trang |

**Payload:** `FormData` với file PDF (`application/pdf`)

**File:** `src/app/api/autoshopee/service/pdf.js`

### S3 Storage Service

**Base URL:** `https://s3-store-api.autoshopee.com`

Dịch vụ lưu trữ file trên S3.

| Hàm | Method | Endpoint | Mô tả |
|-----|--------|----------|-------|
| `uploadS3OrderPrintPdf` | PUT | `/{bucket}/{fileName}` | Upload PDF phiếu in đơn hàng lên S3 |
| `getS3FileUrl` | - | `/{filePath}` | Tạo URL truy cập file trên S3 |

**Bucket:** `order-print`

**File:** `src/app/api/autoshopee/service/s3.js`

### KV Store (Key-Value Storage)

**Base URL:** `https://store-kv-api.autoshopee.com/api/kv`

Dịch vụ key-value storage dùng để cache dữ liệu phía server, hỗ trợ mã hóa và TTL.

| Hàm | Method | Endpoint | Mô tả |
|-----|--------|----------|-------|
| `set` | POST | `/set` | Lưu giá trị (hỗ trợ TTL, mã hóa) |
| `get` | GET | `/get` | Đọc giá trị (hỗ trợ giải mã) |
| `del` | POST | `/delete` | Xóa giá trị |
| `exists` | GET | `/exists` | Kiểm tra key tồn tại |
| `info` | GET | `/info` | Lấy thông tin key (TTL, metadata) |
| `setTtl` | POST | `/ttl` | Cập nhật TTL cho key |
| `lock` | POST | `/lock` | Khóa key (distributed lock) |
| `unlock` | POST | `/unlock` | Mở khóa key |
| `getLockState` | GET | `/state` | Kiểm tra trạng thái khóa |

**File:** `src/app/plugins/kv/adapter.js`, `src/app/plugins/kv/api.js`

### Worker API

**Base URL:** `{VITE_WORKER_URL}`

Proxy API cho Shopee, xử lý các tác vụ crawl/fetch dữ liệu.

| Hàm | Method | Endpoint | Mô tả |
|-----|--------|----------|-------|
| `getCategoryTree` | GET | `/shopee/category/getCategoryTree` | Lấy cây danh mục Shopee |
| `getCategoryList` | GET | `/shopee/category/getCategoryList` | Lấy danh sách danh mục Shopee |
| `fetchListProductCategoryId` | POST | `/shopee/product/fetchProductListCategoryId` | Lấy sản phẩm theo danh mục |
| `fetchListProductShopId` | POST | `/shopee/product/fetchProductListShopId` | Lấy sản phẩm theo shop |
| `getFetchJobId` | GET | `/job/getJobId` | Lấy thông tin job fetch |
| `handlderJobFetch` | POST | `/job/handlerJobFetch` | Xử lý job fetch |
| `getJobFetchWorkerId` | GET | `/job/getJobFetchWorkerId` | Lấy job fetch theo worker |
| `handlerJobFetchWorkerId` | POST | `/job/handlerJobFetchWorkerId` | Xử lý job fetch theo worker |

**File:** `src/app/api/worker/shopee.js`, `src/app/api/worker/fetch.js`

### CouchDB Sync

**Base URL:** `https://store-extension-api.autoshopee.com`

Đồng bộ dữ liệu PouchDB (local IndexedDB) với CouchDB (remote).

- **Mode:** Live replication (two-way)
- **Retry:** Tự động retry khi mất kết nối
- **Auth:** Cookie-based session authentication
- **Class:** `ModelApiLoader` kế thừa PouchDB

**File:** `src/app/api/model.js`

---

## WebSocket Services

### Socket.io - App

**URL:** `{VITE_SOCKET_URL}`

Kết nối real-time giữa extension và server AutoShopee.

| Event | Mô tả |
|-------|-------|
| `connect` | Kết nối thành công |
| `disconnected` | Mất kết nối |
| `extension:auth` | Xác thực extension |

**Auth payload:** `{ ref, version, manifest, token, username, id }`

**File:** `src/app/socket/app.js`

### Socket.io - Worker

**URL:** `{VITE_WORKER_SOCKET}`

Kết nối real-time cho hệ thống worker fetch dữ liệu.

| Event | Mô tả |
|-------|-------|
| `connect` | Kết nối thành công |
| `disconnected` | Mất kết nối |
| `fetch-url-worker-id` | Nhận URL cần fetch theo worker |
| `fetch-url-job-request` | Yêu cầu fetch URL |
| `fetch-url-job-recived` | Xác nhận đã nhận job |
| `worker-set-indentify` | Thiết lập danh tính worker |
| `worker-ready-up` | Worker sẵn sàng nhận việc |
| `worker-ready-down` | Worker ngừng nhận việc |

**File:** `src/app/socket/worker.js`

---

## Dịch vụ xử lý hình ảnh

**Base URL:** `{VITE_IMAGE_HANDLER_URL}`

| Hàm | Method | Endpoint | Mô tả |
|-----|--------|----------|-------|
| `openUrlHandlerImage` | GET | `/{type}?url={listImage}` | Xử lý hình ảnh (watermark, xóa nền, thay nền) |

**Type hỗ trợ:**

- `wartermark` - Thêm watermark
- `removebg` - Xóa nền
- `replacebg` - Thay nền

**File:** `src/app/api/image.js`

---

## Tiện ích chung

### Fetch PDF từ URL

| Hàm | Method | Endpoint | Mô tả |
|-----|--------|----------|-------|
| `getPdfFromUrl` | GET | `{url}` (bất kỳ) | Tải file PDF từ URL bất kỳ (trả về ArrayBuffer) |

**File:** `src/app/api/utils/get.js`

---

## Tổng hợp domain bên ngoài

| Domain | Loại | Mục đích |
|--------|------|----------|
| `shopee.vn` | Shopee Client | API mua hàng |
| `banhang.shopee.vn` | Shopee Seller | API bán hàng |
| `open-api.affiliate.shopee.vn` | Shopee Affiliate | API tiếp thị liên kết (GraphQL) |
| `seller-push-ws.shopee.vn` | Shopee Chat WS | WebSocket chat real-time |
| `cf.shopee.vn` | Shopee CDN | Hình ảnh sản phẩm |
| `cvf.shopee.vn` | Shopee CDN | Video sản phẩm |
| `shop-vn.tiktok.com` | TikTok Client | API shop TikTok |
| `seller-vn.tiktok.com` | TikTok Seller | API seller TikTok |
| `lazada.vn` | Lazada Client | API Lazada |
| `sellercenter.lazada.vn` | Lazada Seller | API seller Lazada |
| `gpt-api.autoshopee.com` | AutoShopee GPT | AI sinh nội dung |
| `service-3rd.autoshopee.com` | AutoShopee PDF | Xử lý PDF |
| `s3-store-api.autoshopee.com` | AutoShopee S3 | Lưu trữ file S3 |
| `store-kv-api.autoshopee.com` | AutoShopee KV | Key-value storage |
| `store-extension-api.autoshopee.com` | AutoShopee CouchDB | Đồng bộ database |
| `{VITE_API_URL}` | AutoShopee API | API chính (auth, shop, product) |
| `{VITE_CMS_URL}` | AutoShopee CMS | Nội dung CMS |
| `{VITE_WORKER_URL}` | AutoShopee Worker | Worker proxy API |
| `{VITE_SOCKET_URL}` | AutoShopee Socket | WebSocket real-time |
| `{VITE_WORKER_SOCKET}` | AutoShopee Worker WS | WebSocket worker |
| `{VITE_IMAGE_HANDLER_URL}` | AutoShopee Image | Xử lý hình ảnh |
