NWi跨境电商数据洞察
目录
- 基础信息
- api_key 管理
- 参考文件路由（按域加载）
- 额度计算规则
- 工作流
- 权限受限处理
- 常见问题 FAQ
- 关键规则速查
基础信息
- 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：整理结果
- 汇总为表格或报告形式
- 确保统计正确（注意字符串类型字段需转换）
- 发送给用户
权限受限处理
| 错误类型 | 处理方式 |
|---|---|
| 时间超限 | 调用 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的「达人必读约束」 - 禁止编造数据：缺少接口或维度时不得猜测或编造，必须告知用户当前权限/接口不支持
