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 管理

1. 检查现有 key: 读取 references/api_key.txt，存在则直接使用
2. 获取新 key（无 key 或失效时）:
   • 调用 generate-normal-api-key 接口,无需询问用户
   • 用户也可手动提供 key
3. 保存 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），在发起请求前必须：

1. 估算本次消耗：
   • 月数：大盘接口按 start_month/end_month，达人接口按 date_start/date_end 所跨越的自然月数 = (end 年 - start 年) × 12 + (end 月 - start 月) + 1
   • 平台数：大盘接口传了 platform_ids 按实际数量算、未传按该 key 有权限的全部平台数算（调用 get-platform-list 获取）；达人接口按 market_id 算，单站 = 1
   • 消耗 = 月数 × 平台数
2. 提示用户：告知用户"本次查询将消耗约 X 额度（Y 个月 × Z 个平台）"
3. 等待确认：必须等用户明确回复确认（如"确认"/"可以"/"好的"）后，才可发起请求
4. 豁免情况：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 的「达人必读约束」
• 禁止编造数据：缺少接口或维度时不得猜测或编造，必须告知用户当前权限/接口不支持