08开放 API 文档

全球商品情报开放接口 · 拍照搜源 / 对标报告 / 供应链簇 / 候选池 / 工商企业 / 商品市场 / 趋势情报
认证方式: 请求头 X-API-Key（外部调用必填，缺失返回 401）· key 用户默认 1,000 次/天 · 自有服务器 IP 免 key
门户自带页面（驾驶舱/市场面板/候选池等）所需接口保持匿名可用（限流 30 次/分）
海外企业信息采集方案 → 海外企业信息查询（GLEIF / SEC / Companies House 等）

获取 key 流程：① 提交申请（获得申请编号+口令）→ ② 等待审核（通常 24h 内）→ ③ 凭编号+口令在领取页查看你的 key → ④ 请求时加 Header：X-API-Key: gpi_xxxx...

A 拍照搜源 B 对标报告 C 供应链簇 D 候选/统计 E 工商企业 F 海外企业 G 商品市场 H 趋势需求 I 情报任务 J 搜图/追踪 K DNA/采集 L 机器人错误码

A拍照搜源（核心接口）

POST /v1/snap/search

上传商品照片（JPEG/PNG，≤12MB，建议 800px），返回海外同款、机会评分、总结段、1688 货源（如已回填）。垃圾图会被拦截（rejected=true）。

curl -X POST https://global.ywworld.cn/v1/snap/search \
  -H "X-API-Key: gpi_xxxx" -H "Content-Type: application/json" \
  -d '{"b64": "<base64图片数据>"}'

# 返回
{"ok": true,
 "matches": [{"market":"ebay_api","title":"...","price_cny":49.2,
              "score":0.91,"score100":{"total":62,...},
              "supply":[{"price_cny":8.5,"city":"义乌",...}]}],
 "summary": [{"icon":"🌍","text":"海外行情: ..."},
             {"icon":"🏭","text":"1688 货源: ..."},
             {"icon":"💰","text":"利润空间: ..."},
             {"icon":"🎯","text":"综合判断: ..."}],
 "best_report": "/m/xxxxxxxx"}

B对标报告

GET /v1/m/{pid}

单品完整对标数据（货源卡/价格带/同款簇/评分）。pid 可从 snap/search 的 matches[].pid 或 best_report 获取。

curl -H "X-API-Key: gpi_xxxx" https://global.ywworld.cn/v1/m/yiwu-amini-dd37ba

C供应链同款簇

GET /v1/supply/clusters?page=1&page_size=10&min_n=2

同款簇列表（按成员数排序）。返回 total + clusters[]（每簇含成员、价格带、平台分布）。

curl -H "X-API-Key: gpi_xxxx" "https://global.ywworld.cn/v1/supply/clusters?page=1&page_size=5"

GET /v1/supply/cluster/{pid}

单簇详情：全部成员（1688 供应商含价格/城市/月销）、中位价。

curl -H "X-API-Key: gpi_xxxx" https://global.ywworld.cn/v1/supply/cluster/2bad63ff010e

D候选池与统计

GET /v1/candidates

候选池（影子对象，评分排序）。

GET /v1/m/stats

全局统计：库规模、各市场数据量、评分漏斗。

GET /v1/m/health

系统健康（采集/向量/队列状态）。

E企业信息查询

GET /v1/ent?name=企业名　或　?uscc=统一社会信用代码

按企业名 / 统一社会信用代码查工商信息：企业全称、法定代表人、注册资本、成立日期、经营范围、电话/邮箱/官网；并含股东/高管/对外投资/被执行/失信等维度。多源合并 (88查 + 风鸟)。

curl -H "X-API-Key: gpi_xxxx" "https://global.ywworld.cn/v1/ent?uscc=91330782MAD93L2994"
curl -H "X-API-Key: gpi_xxxx" "https://global.ywworld.cn/v1/ent?name=义乌市芬纳芮工艺品有限公司"

GET /v1/ent/lookup?name=... 或 ?uscc=...　·　GET /v1/ent/stats

统一企业查询：一次返回 风鸟(工商/股东/高管/风险) + 海关信用名录；stats 为企业库统计。

curl -H "X-API-Key: gpi_xxxx" "https://global.ywworld.cn/v1/ent/lookup?uscc=91330782MAD93L2994"

GET /v1/customs?uscc=... 或 ?name=...

海关企业信用名录：信用等级 / 属地海关 / 适用信用等级时间 / 分类 (高级认证·认证·失信·报关·跨境电商等)。

curl -H "X-API-Key: gpi_xxxx" "https://global.ywworld.cn/v1/customs?uscc=91110000100000833K"

F海外企业信息查询（按需）

GET /v1/ovs/query?name=企业名　·　GET /v1/ovs?name=... 或 ?reg_no=<LEI/CIK/注册号>

按需实时聚合：企知道「全球海外企业」+ GLEIF(全球LEI) + SEC EDGAR(美国) → 字段归一化并缓存；ovs 读缓存。字段：source/country/name/reg_no/status/address/legal_form/directors/... 数据源均为公开登记信息。详见 → 海外企业信息方案。

curl -H "X-API-Key: gpi_xxxx" "https://global.ywworld.cn/v1/ovs/query?name=Apple"

G商品 / 市场检索

GET /v1/listings

商品检索（全库）。参数：market 平台、q 关键词、has_price/has_image、status、min_quality、min_sim、sort、page、has_moq。

curl -H "X-API-Key: gpi_xxxx" "https://global.ywworld.cn/v1/listings?q=保温杯&market=ebay_api&has_image=1&page=1"

GET /v1/export/listings

导出商品（fmt 格式、market、q、sort 等，同 listings 过滤）。

GET /v1/products?q=&cat=&status=&page=

产品库（已归一化产品）。

GET /v1/markets

平台/市场列表 + 规模。

GET /v1/market-panel/{key}

某市场/品类的面板数据（价格带、分布）。

GET /v1/data-quality　·　GET /v1/listings/status

数据质量指标 / 采集与入库状态。

H趋势 / 需求 / 异常

GET /v1/trend/ranking?limit=　·　GET /v1/trend/aibuy?limit=

热销趋势榜 / 1688 趋势。

GET /v1/demand/stats　·　GET /v1/demand/amz-bs?limit=

需求池统计 / 亚马逊 BestSeller 需求。

GET /v1/anomaly?market=&page=&page_size=

异常清单（价格/数据异常）。

I情报任务（异步）

POST /v1/product-intel → GET /v1/product-intel/{job_id}

提交单品/单图情报任务，返回 job_id；轮询取结果。

POST /v1/intel/batch　→　GET /v1/intel/batch　·　GET /v1/intel/batch/{bid}

批量情报：提交一批 → 查批次列表/详情。

POST /v1/match/listing　·　POST /v1/enrich

商品匹配 / 对象补全。

J以图搜图 / 快照 / 追踪

POST /v1/aibuy/imgsearch → GET /v1/aibuy/imgsearch/{sid}

1688 以图搜同款（必须异步）：提交图片 → 返回 sid → 轮询结果。一次约 60–230 秒（受上游和暖机影响，10-03 实测），轮询间隔建议 10 秒、超时给到 300 秒，别当同步接口用。上游近期全失败时本接口返 503 并在正文里写原因，属保护性放行失败，不是你的参数错。
⚠️ 10-03 复核：先别接入生产，但原因不是上游。当天上午那轮"20 条零重合、没有一条对题"其实是我们自己的图床缺一个响应头：站内图 showtime.ywworld.cn 不发 Access-Control-Allow-Origin，浏览器 GET 到 200 却读不到字节，上传（image.upload）一次都没发生，收到的是落地页自己发的默认推荐。12:43 已在图床补上该头。补完用线上函数本体拿两张互不相干的站内图各跑一次：不锈钢分格饭盒 → 20 条全是不锈钢饭盒/便当盒（8.0–31.8 元）；卡通手持风扇 → 20 条全是小风扇（2.9–9.9 元）；两批标题零重合、各自对题，单次约 184 秒。仍不接入的理由：相关性只有这 2 张样本人读标题判定，不是自动打分，站外图未进这一轮。按图找货请走 POST /v1/match/listing（吃图片、走我们自己的向量库，10-02 起线上可用）。

GET /v1/snap/history?limit=

历史搜图记录。

GET/POST /v1/track　·　GET/DELETE /v1/track/{wid}　·　POST /v1/track/{wid}/scan

关键词追踪：列表/新增/详情/删除/手动扫描。

K站点 DNA / 基准 / 采集触发

GET /v1/dna/list　·　GET /v1/dna/{did}/history

站点 DNA 列表 / 历史。

POST /v1/dna/register　·　/v1/dna/detect　·　/v1/dna/analyze

GET /v1/benchmark/{key}　·　/v1/benchmark/{key}/history

基准对比与历史。

POST /v1/ss/collect　·　/v1/ssweb/collect　·　/v1/huopan/collect　·　/v1/trend/*/collect　·　POST /v1/supply/ingest

触发各类采集（SellerSprite/货盘/趋势/货源入库）。多为内部/运维用。

L机器人 · 客商雷达（另一主机）

该组接口在 47 主机（同域名代理），鉴权用查询参数 ?tok=<DEV_TOKEN>（联调用途）。

GET /v1/buyers?q=&country=&limit= 找买家/客户。

GET /v1/chakeshang/stats?key= 客商统计。

GET /v1/dev/chat?text=&u=&tok= 跑一句对话（联调）。

GET /v1/dev/push?text=&tok=　·　/v1/dev/pushapp?text=&tok= 微信 / 企业微信推送。

GET /v1/dev/trigger?op=&phrase=&cap=&tok= 触发指定能力。

POST /v1/dev/llm　·　POST /v1/dev/run 走 LLM / 跑脚本。

分享链接（可嵌网页）

客商 /c/{pid}?t={token} · 产品 /p/{pid} · 名片图 /c/{pid}/card.png?t= · 二维码 /qr.png?d=

M错误码

401	key 无效 / 停用 / 过期
429	超出配额或匿名限流
rejected=true	图片未识别到产品（snap 特有，不计费）

申请 API Key → 查询申请状态管理入口 →