NWi跨境电商数据洞察

基础信息

API 域名: https://asia-test-private.nint.hk
认证: URL参数 api_key
响应格式: JSON，code: 0 成功，code: 1 失败
月份格式: yyyy-MM（支持跨月范围查询）
ID参数: platform_ids、brand_ids、cid_ids 均为可重复参数
请求方式: 所有接口使用 POST 请求，参数以 JSON body 传递；优先使用 curl 命令工具

api_key 管理

检查现有 key: 读取 references/api_key.txt，存在则直接使用
获取新 key（无 key 或失效时）:
- 选项1：自动申请临时 key（generate-normal-api-key，权限受限）
- 选项2：用户手动提供
- 选项3：在NWi诺舟数智官网申请试用，等待客服联系(申请试用链接：https://nexus.nint.hk/register?origin_id=22)
保存 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：匹配用户意图

用户意图 → 接口映射表

用户需求	推荐接口	必选参数	说明
查某品类在各站点销售分布	C7	cid_ids	品类分站详情
查某品类 Top 品牌/店铺	C8/C9	cid_ids	品类排行
查某品牌在各站点表现	B6	brand_ids, cid_ids	品牌分站详情+热销品
查某品牌总体概况	B5	brand_ids, cid_ids	品牌汇总数据
查某站点品类销售占比	A1	platform_ids（可选）	类目分布
查某站点 Top 品牌/店铺/商品	A2/A3/A4	platform_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：构造请求

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

步骤 5：解析响应

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

步骤 6：数据校验与异常上报

异常检测标准

异常类型	检测条件	告警级别
量级异常	知名品牌单月单站 < 10万 CNY	🔴 高
数据缺失	知名品牌在人口大国（印尼/泰国等）无数据	🔴 高
趋势异常	同比/环比波动 > 50% 且无合理解释	🟡 中
品牌匹配存疑	模糊匹配且多个相似结果	🟡 中

异常上报流程

检测到异常时，在结果中用⚠标注️，并询问用户是否上传异常。获得用户授权后调用 record-openclawd-anomaly 接口上报。

步骤 7：整理结果

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

权限受限处理

错误类型	处理方式
时间超限	调用 `get-current-api-key-allow-range` 告知可查范围
key 过期/无效	按 api_key 管理流程重新获取
权限不足	提示用户，并发送申请试用链接(`https://nexus.nint.hk/register?origin_id=22`)给用户,提示申请试用可获取更多权限

常见问题 FAQ

Q: 查询某品牌时返回空数据怎么办？ A: 1) 检查品牌名是否正确匹配 2) 确认该品类是否有销售 3) 确认时间范围内有数据

Q: 为什么 B6 必须传 cid_ids？ A: 品牌可能跨多个品类销售，需指定品类范围才能准确统计

Q: 临时 api_key 有什么限制？ A: 权限范围较小，可能只支持部分站点/时间，建议到NWi诺舟数智官网申请试用获取完整权限

Q: 如何查看品牌在各站点的热销商品？ A: 使用 B6 接口，返回的 top_items 包含各站点 Top 商品

Q: A4 Top 商品接口为什么不支持品牌筛选？ A: 该接口设计为全站商品排行，品牌筛选请使用 B6 接口

关键规则速查

站点 = 电商平台 + 国家（如亚马逊@美国 ≠ 亚马逊@新加坡）
非必选参数不传 = 不限制该维度
A4: platform_ids 实际必选；不支持 brand_ids
B5/B6: brand_ids 和 cid_ids 均为必选
C7/C8/C9: cid_ids 为必选
A1 无 platform_ids: 返回所有有权限市场的汇总
B6 多 brand_ids: 返回合并数据，不区分品牌
cid_ids 支持多层级: 可传入任意层级品类ID（一级/二级/三级）
sales_total/percentage: 字符串类型，需 float() 转换

nwi-ecommerce

Safety Notice

Copy this and send it to your AI assistant to learn