NWi跨境電商資料分析
📖 技能介紹
name: nwi-ecommerce version: 0.0.18 description: NWi諾舟智數提供的跨境電商資料洞察（Amazon/Shopee/Lazada/TikTok/Ozon）。觸發詞：電商資料、銷量、銷額、品類分佈、品牌排行、店鋪排行、東南亞市場、俄羅斯電商、評論分析、達人分析
NWi跨境電商資料洞察
目錄
基礎資訊
- API 域名:
https://asia-test-private.nint.hk - 認證: JSON body 引數
api_key - 響應格式: JSON，
code: 0成功，code: 1失敗 - 月份格式:
yyyy-MM（支援跨月範圍查詢） - ID引數:
platform_ids、brand_ids、cid_ids均為可重複引數 - 請求方式: 所有介面使用 POST 請求，引數以 JSON body 傳遞；Windows下優先使用 PowerShell Invoke-RestMethod進行請求, Linux環境下則使用 curl 命令工具
api_key 管理
- 檢查現有 key: 讀取
references/api_key.txt，存在則直接使用 - 獲取新 key（無 key 或失效時）:
- 呼叫
generate-normal-api-key介面,無需詢問使用者 - 使用者也可手動提供 key
- 儲存 key: 獲取後寫入
references/api_key.txt
參考檔案路由（按域載入）
按使用者意圖只加載相關檔案，避免一次性讀入全部介面文件：
| 何時載入 | 檔案 | 內容 |
|---|---|---|
| 任何查詢前（通用） | references/api-common.md |
請求/響應格式、錯誤碼、欄位型別、分頁約定 |
| 大盤類問題（品類分佈/排行/彙總/增長/評論） | references/api-market.md |
A/D/E 組介面 + 前置介面（平臺/品類/品牌搜尋） |
| 達人類問題（達人/直播/影片/品牌達人/榜單） | references/api-creator.md |
CA/CB/CC/CD 組介面 + 達人必讀約束 |
| 需要平臺 ID | references/platform_ids.md |
平臺 ID 速查表 |
⚠️ 達人查詢專用：呼叫任何 TikTok 達人介面前，務必先讀
references/api-creator.md頂部的「達人必讀約束」（達人≠大盤、market_id、先探 solidified-date、帶貨 vs 商城 GMV、CC 先搜 brand_id 五條鐵律）。
額度計算規則
額度消耗公式
資料查詢介面的額度按 月數 × 平臺數 計算：
不消耗額度的介面（前置/管理類）：
| 介面 | 消耗 |
|---|---|
get-platform-list |
0 |
get-current-api-key-allow-range |
0 |
get-solidified-date（達人資料可用範圍，傳 market_id） |
0 |
固定消耗 1 的介面：
| 介面 | 消耗 |
|---|---|
get-brand-list |
1 |
get-top-category-list |
1 |
get-all-category-list-by-name |
1 |
get-submit-contact-info-url |
1 |
version |
1 |
CA1 get-creator-detail-basic-meta（達人基礎資訊，無時間引數） |
1 |
按「月數 × 平臺數」消耗的介面（資料查詢類）：
| 介面 | 消耗公式 | 說明 |
|---|---|---|
A1 get-global-primary-categories |
月數 × 平臺數 | 類目分佈 |
A2 get-global-top-brands-list |
月數 × 平臺數 | Top品牌排行 |
A3 get-global-top-shop-list |
月數 × 平臺數 | Top店鋪排行 |
A4 get-global-top-items-list |
月數 × 平臺數 | Top商品排行 |
A5 get-data-summary |
月數 × 平臺數 | 資料彙總 |
D1 get-high-growth-brand-list |
月數 × 平臺數 | 高速增長品牌 |
D2 get-potential-brand-list |
月數 × 平臺數 | 潛力品牌 |
D3 get-potential-hot-items-list |
月數 × 平臺數 | 潛力爆款商品 |
E1 get-review-analysis |
月數 × 平臺數 | 評論分析 |
| CA2~CA7 / CB1 / CC2~CC8 / CD1~CD2（達人分析帶時間引數介面） | 月數 × 平臺數 | 達人分析，按 date_start/date_end 涉及的自然月數 × market_id 數計費 |
月數計算：
- 大盤介面（A/D/E 組）按 start_month/end_month：(end 年 - start 年) × 12 + (end 月 - start 月) + 1
- 達人介面（CA/CB/CC/CD 組）按 date_start/date_end 所跨越的自然月數，公式同上
平臺數計算：
- 大盤介面傳了 platform_ids → 取傳入的 ID 數量；未傳 → 取該 api_key 有許可權的全部平臺數量
- 達人介面按 market_id 計算（market_id 即 platform_id，TikTok × 國家站），單次請求查一個站點 = 1
示例：查詢 2025-01~2025-03 共 3 個月、Shopee 3 個站點 → 消耗 = 3 × 3 = 9
響應中的額度欄位
每次介面響應中包含：
- cost：本次請求消耗的額度（數字型別）
- remaining_quota：剩餘可用額度（數字型別，"無上限" 表示無限制）
工作流
步驟 1：載入資源
按「參考檔案路由」按需載入：先讀 references/api-common.md，再按問題型別讀 api-market.md 或 api-creator.md，需要平臺 ID 時讀 references/platform_ids.md。
步驟 2：獲取許可權範圍
呼叫前置介面（無需月份引數）：
- get-platform-list → 有許可權的站點列表
- get-top-category-list → 一級品類列表
- get-all-category-list-by-name → 按關鍵詞搜尋品類（支援中英文，返回多層級）
- get-current-api-key-allow-range → 可查詢時間範圍（api_key 許可權範圍）
- get-solidified-date → 達人資料實際可用範圍（按 market_id，查詢達人介面前呼叫）
步驟 3：匹配使用者意圖
使用者意圖 → 介面對映表
| 使用者需求 | 推薦介面 | 必選引數 | 說明 |
|---|---|---|---|
| 查某站點品類銷售佔比 | A1 | 無必選（均可選） | 類目分佈；可選 cid 引數下鑽檢視子類目分佈 |
| 查全站 Top 品牌 | A2 | 無必選（均可選） | 綜合排行，不傳 platform_ids=全平臺彙總，不帶平臺欄位 |
| 查全站 Top 店鋪 | A3 | 無必選（均可選） | 綜合排行，不傳 platform_ids=全平臺彙總 |
| 查全站 Top 商品 | A4 | platform_ids | ⚠️ platform_ids 必選，不傳返回空 |
| 查高速增長品牌 | D1 | platform_ids, cid_ids | 高速增長品牌排行(含同比增速) |
| 查潛力品牌 | D2 | platform_ids, cid_ids | 潛力品牌排行(含同比增速) |
| 查潛力爆款商品 | D3 | platform_ids, cid_ids | 潛力爆款商品排行 |
| 查某條件下的銷量/銷額/均價 | A5 | platform_ids/brand_ids/cid_ids至少一個 | 資料彙總，返回平臺/品牌/品類+銷量銷額均價 |
| 指定範圍商品評論分析 | E1 | platform_ids, start_month, end_month, brand_id+cid_id/shop_id/item_id | 評論分析，按品牌/店鋪/商品查詢評論 |
| 查 TikTok 達人排行 | CB1 | market_id | 達人排行榜，支援按 GMV/粉絲數/直播GMV/影片GMV 等排序，欄位含 live/video 渠道拆分 |
| 查 TikTok 達人詳情 | CA1 / CA2 | creator_id, market_id | 達人基礎資訊(CA1) + 帶貨資料(CA2, 可選 date_start/date_end) |
| 查 TikTok 達人趨勢 | CA3 | creator_id, market_id, trend_type | 指定指標的日級趨勢 |
| 查 TikTok 達人帶貨分佈 | CA4 | creator_id, market_id, date_start, date_end | 按載體/類目/品牌/店鋪的 GMV 分佈 |
| 查 TikTok 達人影片/直播/商品 | CA5 / CA6 / CA7 | creator_id, market_id, date_start, date_end | 達人內容列表，含互動率/GPM/客單價/渠道拆分 |
| 查 TikTok 品牌達人資料 | get-brand-list→CC2→CC3~CC8 | 見介面文件 | 先用 get-brand-list 搜品牌拿 brand_id，再查詳情(CC2, 需date_start/date_end)和關聯達人/商品/直播/影片 |
| 查 TikTok 品牌/店鋪排名 | CD1 / CD2 | market_id, date_start, date_end | 品牌/店鋪榜單，區分帶貨 GMV vs 商城 GMV(trade_*)，含 live/video 渠道拆分 |
大盤組（A/D/E）介面細節見
references/api-market.md；達人組（CA/CB/CC/CD）介面細節及匹配流程（品牌/品類/達人品牌匹配）見references/api-creator.md。
步驟 4：額度估算與使用者確認（⚠️ 資料查詢介面必須執行）
對於資料查詢類介面（A1~A5、D1~D3、E1，以及帶時間引數的達人介面 CA2~CA7/CB1/CC2~CC8/CD1~CD2），在發起請求前必須：
- 估算本次消耗：
- 月數：大盤介面按
start_month/end_month，達人介面按date_start/date_end所跨越的自然月數 = (end 年 - start 年) × 12 + (end 月 - start 月) + 1 - 平臺數：大盤介面傳了
platform_ids按實際數量算、未傳按該 key 有許可權的全部平臺數算（呼叫get-platform-list獲取）；達人介面按market_id算，單站 = 1 - 消耗 = 月數 × 平臺數
- 提示使用者：告知使用者"本次查詢將消耗約 X 額度（Y 個月 × Z 個平臺）"
- 等待確認：必須等使用者明確回覆確認（如"確認"/"可以"/"好的"）後，才可發起請求
- 豁免情況：
remaining_quota為"無上限"時可跳過確認，直接請求
前置介面及無時間引數的 CA1
get-creator-detail-basic-meta（固定消耗 1）不需要確認，直接請求。
步驟 5：構造請求
- 檢查必選引數是否齊全
- 缺失時詢問使用者或使用預設值（如時間範圍使用許可權內最新月份）
- 構造請求
步驟 6：解析響應
根據介面型別解包 data，詳見對應 reference 檔案中的響應結構/解析路徑。
步驟 7：額度與版本檢查
每次介面響應中包含 cost（本次消耗）、remaining_quota（剩餘額度）和 latest_skill_version（最新 skill 版本），需檢查：
- 本次消耗：響應中的
cost欄位表示本次請求實際消耗的額度數 - 額度不足：
remaining_quota為數字且≤ 10時，提醒使用者額度將耗盡；若remaining_quota為字串（如 "無上限"），表示無額度限制，無需提醒 - 版本過舊：
latest_skill_version與當前 skill 版本不一致，或 msg 中提示版本低時，提醒使用者有新版本可用並詢問是否更新
步驟 8：整理結果
- 彙總為表格或報告形式
- 確保統計正確（注意字串型別欄位需轉換）
- 傳送給使用者
許可權受限處理
7w4.net提供免費和付費技能下載。
| 錯誤型別 | 處理方式 |
|---|---|
| 時間超限 | 呼叫 get-current-api-key-allow-range 告知可查範圍 |
| key 過期/無效 | 按 api_key 管理流程重新獲取 |
| 許可權不足 | 提示使用者當前許可權範圍 |
常見問題 FAQ
Q: 查詢某品牌時返回空資料怎麼辦？ A: 1) 檢查品牌名是否正確匹配 2) 確認該品類是否有銷售 3) 確認時間範圍內有資料
Q: A1 介面如何檢視子類目分佈？
A: 不傳 cid 返回一級類目分佈；傳入 cid（數字型別）可下鑽檢視該 cid 下一級子類目分佈
Q: A4 Top 商品介面為什麼不支援品牌篩選？
A: A4 設計為全站商品排行，不支援品牌篩選。支援通過 cid_ids 按品類篩選
Q: A5 資料彙總介面的條件要求？
A: platform_ids、brand_ids、cid_ids 三個條件至少需要傳入一個，全部為空則返回錯誤。可以同時傳入多個條件做交叉篩選。返回結果中會包含 platform/brand/category 欄位，未傳的條件顯示為 "all"，已傳的顯示具體名稱
Q: A4 為什麼必須傳 platform_ids？
A: A4 與 A2/A3 不同，不傳 platform_ids 會返回空資料。需至少指定一個平臺 ID
Q: E1 評論分析介面支援批次查詢嗎？ A: 不支援。三種查詢方式（品牌+類目/店鋪/商品）均為單值查詢。如需對比多個品牌/店鋪/商品的評論，請發起多次請求。
Q: E1 返回"目標資料正在處理中"是什麼意思？ A: 該查詢條件下評論數不足 50 條，已自動建立資料爬取任務。請 2 天后再來查詢。
關鍵規則速查
- 站點 = 電商平臺 + 國家（如 亞馬遜@美國 ≠ 亞馬遜@新加坡）
- 非必選引數不傳 = 不限制該維度
- D1/D2/D3:
platform_ids和cid_ids均為必選；brand_ids為可選 - A1: 不傳
cid返回一級類目分佈；傳入cid可下鑽檢視下一級子類目分佈 - A5:
platform_ids、brand_ids、cid_ids至少傳一個，返回銷量/銷額/均價彙總；未傳的條件欄位顯示 "all"，已傳顯示具體名稱 - E1:
platform_ids必選，brand_id+cid_id（按品牌查詢時必須同時傳）、shop_id、item_id三選一；評論數 < 50 條時自動移除時間限制擴充套件到全量歷史資料，全量仍不足才建立爬取任務；≥ 50 條最多返回 200 條 - cid_ids 支援多層級: 可傳入任意層級品類ID（一級/二級/三級）
- 達人組（CA/CB/CC/CD）: 站點引數用
market_id、時間引數用date_start/date_end，呼叫前先讀references/api-creator.md的「達人必讀約束」 - 禁止編造資料：缺少介面或維度時不得猜測或編造，必須告知使用者當前許可權/介面不支援
🤖 AI 評測
這是一個功能豐富的跨境電商資料查詢工具，支援五大平臺、覆蓋20+品類，資料查詢和達人分析能力較為全面。文件結構清晰、說明通俗，整體質量較好。主要不足是版本資訊有些混亂，另外某些高階功能（如額度計算、品牌匹配）的配置對新手來說稍顯複雜，需要一定學習成本。適合有電商資料分析需求的使用者使用。.
