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

1. 检查现有 key: 读取 references/api_key.txt，存在则直接使用
2. 获取新 key（无 key 或失效时）:
   • 调用 generate-normal-api-key 接口,无需询问用户
   • 用户也可手动提供 key
3. 保存 key: 获取后写入 references/api_key.txt

工作流

步骤 1：加载资源

• 读取 references/api.md 获取接口规范
• 读取 references/platform_ids.md 获取平台 ID 速查表

步骤 2：获取权限范围

调用前置接口（无需月份参数）：

• get-platform-list → 有权限的站点列表
• get-top-category-list → 一级品类列表
• get-all-category-list-by-name → 按关键词搜索品类（支持中英文，返回多层级）
• get-current-api-key-allow-range → 可查询时间范围

步骤 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至少一个 | 数据汇总，返回平台/品牌/品类+销量销额均价 |

品牌匹配流程

1. 调用 get-brand-list?brand_like=xxx
2. 若结果为空 → 提示用户换关键词或确认品牌名
3. 若多个结果 → 按优先级排序：
   - 精确名称匹配 > 包含匹配
   - sales 参考销额高的优先
4. 展示 TOP 3 供用户确认（自动选择第一名时也需告知）

品类匹配流程

1. 调用 get-all-category-list-by-name?category_like=xxx 按关键词搜索品类
2. 支持中英文关键词搜索，返回多层级品类（含层级路径）
3. 若结果为空 → 换关键词或调用 get-top-category-list 展示所有一级品类供选择
4. 若多个结果 → 展示给用户确认（注意区分 level，告知不同层级的品类范围不同），
5. 若品类跟用户发送的不完全一致，务必让用户二次确认！不可自行选择相似品类！

步骤 4：构造请求

• 检查必选参数是否齐全
• 缺失时询问用户或使用默认值（如时间范围使用权限内最新月份）
• 构造请求

步骤 5：解析响应

根据接口类型解包 data，详见 references/api.md 中的响应结构表。

步骤 6：额度与版本检查

每次接口响应中包含 remaining_quota（剩余额度）和 latest_skill_version（最新 skill 版本），需检查：

• 额度不足：remaining_quota 为数字且 ≤ 10 时，提醒用户额度将耗尽；若 remaining_quota 为字符串（如 "无上限"），表示无额度限制，无需提醒
• 版本过旧：latest_skill_version 与当前 skill 版本不一致，或msg中提示版本低时，提醒用户有新版本可用并询问是否更新

步骤 7：整理结果

• 汇总为表格或报告形式
• 确保统计正确（注意字符串类型字段需转换）
• 发送给用户

权限受限处理

| 错误类型 | 处理方式 | |---------|---------| | 时间超限 | 调用 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

关键规则速查

• 站点 = 电商平台 + 国家（如 亚马逊@美国 ≠ 亚马逊@新加坡）
• 非必选参数不传 = 不限制该维度
• D1/D2/D3: platform_ids 和 cid_ids 均为必选；brand_ids 为可选
• D1: 返回 highGrowthBrandList，按平台分组，关键字段：brand_id, brand_name, sales_total, num_total, avg_price, yoy_growth_rate
• D2: 返回 potentialBrandList，结构同 D1
• D3: 返回 potentialHotItemList，按平台分组，关键字段：item_id, item_name, sku_id, img, sales_total, num_total, avg_price, _cid, cate_name, full_cate_name
• A1: 不传 cid 返回一级类目分布；传入 cid 可下钻查看下一级子类目分布
• A5: platform_ids、brand_ids、cid_ids 至少传一个，返回销量/销额/均价汇总；未传的条件字段显示 "all"，已传显示具体名称
• cid_ids 支持多层级: 可传入任意层级品类ID（一级/二级/三级）
• 禁止编造数据：缺少接口或维度时不得猜测或编造，必须告知用户当前权限/接口不支持