万邦api博客

反向海淘代购系统开发实录：从业务链路到可运行代码

Wed, 14 Oct 2026 15:29:25 +0800

去年有个做缅甸市场的朋友问我：为什么国内代购门店到处都是，国外卖中国货的店却几乎见不到？
不是没需求。中国商品在海外是明确的供给缺口。真正的问题是这条链路太碎了——国内平台不发货海外、不支持外币、客服说中文，中间还横着集运、清关、尾程三段互不相干的履约。
后来我把这套系统从头做了一遍，踩了 8 个坑。这篇把架构和坑都写下来。

一、先定义问题：反向海淘代购系统到底在解决什么

反向海淘（Reverse Cross-border Shopping）指的是：海外用户（海外华人、留学生、本地消费者）购买中国电商平台的商品，由平台方完成代采、集运、清关、派送的全过程。

它和传统海淘正好相反——传统海淘是中国人买外国货，反向海淘是外国人买中国货。

需求真实存在：中国商品的高性价比和丰富度，对海外市场是明显的供给缺口。但海外用户想买，面前横着三堵墙：

阻力	具体表现	本质
渠道不通	淘宝、京东、1688 不面向海外零售，不支持外币支付，不直发海外	国内电商的履约体系不覆盖海外 C 端
履约链太长	国内段物流 + 集运仓 + 国际干线 + 清关 + 尾程，任一环断掉整单就砸	跨境履约是多个独立主体的拼接
本地化缺失	全中文页面、只收人民币、客服无法沟通、退换货无门	缺少面向目标市场的前台与售后体系

代购系统要做的，就是把这条又长又碎的链路，封装成一个海外用户能看懂的、能用本地货币结算的、状态可追踪的购物流程。

一句话概括系统定位：

前端像一个本地电商站，后端是一条自动化的跨境代采流水线。

二、全链路业务流程

在写第一行代码之前，先把业务流画清楚。反向海淘的主链路可以用一张图概括：

┌─ 海外用户视角 ──────────────────────────────────────────┐
│  ① 浏览商品（多语言 · 多币种 · 换算后到手价）              │
│  ② 加入购物车 / 提交代购需求（粘贴链接亦可）               │
│  ③ 支付（本地货币 · 本地支付方式）                        │
│  ④ 查看物流（国内段 → 集运仓 → 国际段 → 本地派送）        │
│  ⑤ 收货 / 评价 / 售后                                   │
└──────────────────────┬──────────────────────────────────┘
                       ↓
┌─ 平台后端视角 ──────────────────────────────────────────┐
│  ⑥ 订单落库 → 生成采购任务                               │
│  ⑦ 代采：按商品链接向国内电商平台下单                     │
│  ⑧ 国内卖家发货 → 集运仓收货                             │
│  ⑨ 入库作业：验货 / 称重 / 量方 / 异常拍照               │
│  ⑩ 合单打包：智能装箱，多单合并降运费                     │
│  ⑪ 国际干线发运 → 出口报关 → 目的国清关                   │
│  ⑫ 尾程派送 → 签收 → 结算对账                            │
└─────────────────────────────────────────────────────────┘

注意这条链路上的三个特征，它们直接决定了架构长什么样：

链路长且跨主体：⑧~⑫ 涉及国内卖家、集运仓、国际渠道、海关、尾程承运商，每一段都有独立的时效和异常。
状态多而不可逆：钱先收、货后采、运费在合单后才能确定，所以状态机必须严谨。
成本构成复杂：商品价 + 国内运费 + 服务费 + 国际运费，其中只有前三项在下单时确定，国际运费是预估值。

三、技术架构分层

一套能承接规模化订单的反向海淘系统，典型分层如下：

┌───────────────────────────────────────────────────────────┐
│ 接入层  自建独立站(Web/H5) · 小程序 · APP · 商家运营后台    │
└─────────────────────────┬─────────────────────────────────┘
                          │  HTTPS
┌─────────────────────────▼─────────────────────────────────┐
│ 网关层  API Gateway                                        │
│  鉴权 / 限流 / 语言识别 / 币种路由 / 灰度                    │
└─────────────────────────┬─────────────────────────────────┘
┌─────────────────────────▼─────────────────────────────────┐
│ 业务服务层                                                 │
│  商品服务 │ 报价引擎 │ 订单服务 │ 采购服务 │ 仓储 WMS       │
│  物流 TMS │ 支付服务 │ 用户服务 │ 翻译服务 │ 消息/通知中心   │
└─────────────────────────┬─────────────────────────────────┘
┌─────────────────────────▼─────────────────────────────────┐
│ 数据层                                                     │
│  MySQL（交易/订单） · Redis（缓存/汇率/会话）               │
│  Elasticsearch（商品检索） · MQ（状态流转/异步任务）         │
│  对象存储（商品图/验货图） · 数据仓库（对账/风控）           │
└─────────────────────────┬─────────────────────────────────┘
┌─────────────────────────▼─────────────────────────────────┐
│ 外部依赖                                                   │
│  国内电商商品数据 API · 跨境支付渠道 · 集运仓系统            │
│  国际物流渠道 · 实时汇率源 · 翻译引擎 · 风控服务             │
└───────────────────────────────────────────────────────────┘

几个设计要点：

报价引擎必须独立成服务，因为它被商品详情页、购物车、结算页、后台订单四处在调用，逻辑一旦散开就必然出现"三个页面三个价"。
状态流转走消息队列，不要直接用数据库事务串起来。⑧~⑫ 每一段都是外部系统，随时超时，必须靠事件驱动 + 定时补偿。
仓储 WMS 不要自己从零写。称重量方、库存位管理、装箱打印都是重活，优先对接成熟集运仓系统，只在中间做一层适配。

四、六大核心模块拆解

4.1 商品同步：为什么"全量爬"这条路走不通

新手最容易踩的坑，是想着把国内平台的商品全量同步到自己站上。按千万级 SKU 算：全量拉一次的成本、存储、更新频率，都是无底洞，而且商品价格和库存是实时变化的，你同步完的那一刻数据就已经旧了。

正确的做法是按需同步 + 分级缓存：

场景	策略	时效要求
用户主动搜索	实时调用搜索接口，结果不落库	秒级
打开商品详情页	实时拉取 + Redis 缓存 5~30 分钟	分钟级
加购未下单	缓存 1 小时，下单前强制刷新价格	必须实时
已下单商品	生成商品快照，永久留存	只读，不再刷新

最后一条是整个系统的关键设计：下单即快照。

商品快照 = {
  商品ID、标题、主图、规格、下单时的价格、
  下单时的汇率、下单时的服务费率、下单时的运费模板
}

有了快照，后续无论国内卖家怎么改价、下架、换图，这笔订单的结算依据都不会变，客诉时也有据可查。没有快照，你会在第一次价格波动时就被客户投诉淹没。

4.2 多币种报价引擎

报价是反向海淘最容易被低估的模块。它要解决三个问题：钱怎么算、汇率用哪个、什么时候锁价。

一笔订单的到手价构成：

到手价 = (商品价 + 国内运费 + 代购服务费 + 预估国际运费) ÷ 结算汇率

其中结算汇率 = 中间价 × (1 + 点差)，点差是平台覆盖汇率波动风险的常规手段。

下面是一个可直接运行的多币种报价实现（示例费率）：

SERVICE_FEE_RATE = 0.08       # 代购服务费率 8%
DOMESTIC_FREIGHT_CNY = 12.0   # 国内段运费
INTL_FREIGHT_CNY = 572.0      # 国际段运费（取自合单结果）
MARKUP = 0.015                # 汇率点差 1.5%

RATES = {"USD": 7.12, "MYR": 1.62, "SGD": 5.31}   # 1 外币 = N 人民币

def quote(goods_cny, currency):
    rate = RATES[currency]
    settle_rate = rate * (1 + MARKUP)          # 用户承担点差
    service = round(goods_cny * SERVICE_FEE_RATE, 2)
    subtotal = goods_cny + DOMESTIC_FREIGHT_CNY + service + INTL_FREIGHT_CNY
    return {
        "settle_rate": round(settle_rate, 4),
        "goods":       round(goods_cny / settle_rate, 2),
        "domestic":    round(DOMESTIC_FREIGHT_CNY / settle_rate, 2),
        "service":     round(service / settle_rate, 2),
        "intl":        round(INTL_FREIGHT_CNY / settle_rate, 2),
        "total":       round(subtotal / settle_rate, 2),
    }

以一件 ¥299 的商品为例，三个市场的报价拆分如下（真实运行输出）：

商品人民币价 ¥299.00 / 服务费率 8% / 汇率点差 1.5%

[USD] 中间价 7.12 → 结算价 7.2268
  商品             41.37 USD
  国内运费          1.66 USD
  代购服务费        3.31 USD
  国际运费         79.15 USD
  合计              125.49 USD   （成本 ¥906.92）

[MYR] 中间价 1.62 → 结算价 1.6443
  商品            181.84 MYR
  国内运费          7.30 MYR
  代购服务费       14.55 MYR
  国际运费        347.87 MYR
  合计              551.55 MYR   （成本 ¥906.92）

[SGD] 中间价 5.31 → 结算价 5.3896
  商品             55.48 SGD
  国内运费          2.23 SGD
  代购服务费        4.44 SGD
  国际运费        106.13 SGD
  合计              168.27 SGD   （成本 ¥906.92）

这个模块最容易出事的两个点：

🔴 汇率必须锁定时点。用户下单时按 7.2268 结算，你在三天后付款采购时汇率可能已经变成 7.35。所以要么下单即锁定、要么在服务费里预留波动空间，绝不能"按实际结算日汇率"——那等于把汇率风险全揽到自己身上。

🔴 国际运费必须标"预估"。合单前的运费是估算值，入库称重后才有准确数字。前端文案要写清楚"预估运费，实际以入库计费为准"，否则超重补款时全是纠纷。

4.3 集运合单：整个系统最能省钱、也最容易被投诉的模块

集运合单是反向海淘的核心竞争力——海外用户往往一次买好几家店的东西，先寄到国内集运仓，合并成一个包裹发出去，能省下大笔国际运费。

关键在于国际快递的计费规则不是按重量算的：

计费重 = max(实重, 体积重)
体积重 = 长(cm) × 宽(cm) × 高(cm) ÷ 系数      # 系数通常 5000 或 6000

也就是说，一箱羽绒服可能只有 2kg 实重，但装箱体积大，按体积重算出来要 9kg —— 这就是代购行业最经典的客诉场景：“明明才两公斤，凭什么收我九公斤的钱？”

下面这段代码同时算了"分开寄"和"合单寄"的成本差，并输出每一个包裹的体积重明细：

import math

DIVISOR = 6000        # 体积重系数
FIRST_HALF = 68.0     # 首重 0.5kg 单价
NEXT_HALF = 28.0      # 续重 每 0.5kg 单价
FILL_RATE = 1.10      # 合单箱体空间损耗系数

def billable_weight(l, w, h, actual):
    """计费重 = max(体积重, 实重)，按 0.5kg 向上进位"""
    vol = l * w * h / DIVISOR
    return math.ceil(max(vol, actual) * 2) / 2, vol

def shipping_fee(charge_kg):
    if charge_kg <= 0.5:
        return FIRST_HALF
    return FIRST_HALF + int(round(charge_kg * 2 - 1)) * NEXT_HALF

def consolidation(parcels):
    total_separate = 0.0
    sum_volume = sum_actual = 0
    for oid, l, w, h, actual in parcels:
        charge, vol = billable_weight(l, w, h, actual)
        total_separate += shipping_fee(charge)
        sum_volume += l * w * h
        sum_actual += actual
    # 合单：箱体体积 = 各包裹体积和 × 空间损耗系数
    box_volume = sum_volume * FILL_RATE
    box_charge = math.ceil(max(box_volume / DIVISOR, sum_actual) * 2) / 2
    return total_separate, shipping_fee(box_charge)

用 5 个真实场景的包裹数据跑一遍，结果如下：

订单号                    体积重kg     实重kg     计费重kg      运费¥
--------------------------------------------------------------
OD20261014001           1.00     1.20      1.50    124.0
OD20261014002           0.90     0.80      1.00     96.0
OD20261014003           3.00     2.50      3.00    208.0
OD20261014004           0.40     0.60      1.00     96.0
OD20261014005           2.92     3.10      3.50    236.0
--------------------------------------------------------------
分开发货：5 个包裹，合计运费 ¥760.0
合单发货：1 个包裹
  ├ 包裹体积累计       49,300 cm³
  ├ 合单箱体估算       54,230 cm³（含 10% 空间损耗）
  ├ 体积重               9.04 kg
  ├ 实重合计             8.20 kg
  ├ 计费重               9.50 kg
  └ 合单运费       ¥572.0
合单节省：¥188.0（降幅 24.7%）

几个工程上的关键决策：

合单收益来自"首重合并"。5 个包裹分开寄要付 5 次首重，合单只付 1 次，这才是省钱的真正来源。包裹件数越多，合单优势越明显。
装箱算法值得投入。上面用的是"体积和 × 损耗系数"的简化模型，工程上应该用 3D 装箱算法（如 py3dbp、首次适应递减 FFD 等）做真实排布，通常还能再挤出 10%~15% 的空间。
计费重必须对用户透明。每个包裹入库后都要有称重照片和量方数据，前端把"体积重 / 实重 / 计费重"三个数字全列出来，客诉率能直接砍掉一大半。信息透明本身就是一种竞争力。

4.4 订单状态机

反向海淘的订单状态比普通电商复杂得多，因为中间插入了采购、入库、合单、清关等环节。用状态机 + 合法转移表来管理，是唯一不会乱的方案：

TRANSITIONS = {
    "待付款":   ["已付款", "已取消"],
    "已付款":   ["采购中", "已退款"],
    "采购中":   ["已采购", "采购失败"],
    "采购失败": ["采购中", "已退款"],       # 允许重新采购
    "已采购":   ["已入库", "异常"],
    "已入库":   ["待合单", "异常"],
    "待合单":   ["已发货", "异常"],
    "已发货":   ["运输中"],
    "运输中":   ["清关中", "异常"],
    "清关中":   ["派送中", "异常"],
    "派送中":   ["已签收", "派送失败"],
    "派送失败": ["派送中", "退件"],
    "异常":     ["已入库", "退件"],
    "已取消": [], "已退款": [], "退件": [], "已签收": [],   # 终态
}

def can_transit(src, dst):
    return dst in TRANSITIONS.get(src, [])

主流程跑起来是这样：

待付款 → 已付款 → 采购中 → 已采购 → 已入库 → 待合单
      → 已发货 → 运输中 → 清关中 → 派送中 → 已签收

异常分支校验：
  ✗ 非法状态转移：已签收 -> 运输中
  ✗ 非法状态转移：已付款 -> 已入库
  ✗ 非法状态转移：采购中 -> 已发货

终态（不可再流转）：已取消、已退款、退件、已签收

三个必须做的工程约束：

所有状态变更必须幂等。物流推送会重复，支付回调会重复，同一个 待发货 → 已发货 可能被触发五次。用订单号 + 目标状态做唯一键去重。
每个状态都要有超时策略。采购中超过 48 小时未完成要自动告警并转人工；已付款超过 24 小时未采购要触发风控。
异常态不是终点，是可恢复的中间态。异常 能回到 已入库 重新作业，采购失败 能回到 采购中 换一家店重采——把异常设计成闭环，比让客服手工改数据库强一万倍。

4.5 多语言与内容本地化

商品标题、描述、规格、参数全部来自国内平台，是中文的。要做本地化，核心不是"翻译得准不准"，而是翻译成本和时效的平衡。

一套实用的策略分层：

内容类型	策略	理由
商品标题	机翻 + 术语库 + 缓存	重复率高，缓存命中后成本几乎为零
规格参数	术语表映射	"颜色/尺码/材质"这类词是有限集合
品牌名、型号	不翻译	机翻会把"Nike Air"翻成奇怪的东西
商品长描述	延迟翻译 / 按需翻译	成本高、访问量低，不值得实时翻
客服会话	实时双向翻译	直接影响转化，必须实时

工程上最关键的优化是翻译缓存：把 原文哈希 → 译文 存进 Redis，同一个商品标题只翻一次，全站所有用户共享。实测能省掉 80% 以上的翻译调用。

4.6 支付与对账

海外支付渠道不能直接写死在业务代码里。正确的做法是渠道抽象层：

PaymentGateway (接口)
  ├─ createPayment(order)      # 创建支付单
  ├─ queryPayment(tradeNo)     # 主动查单
  ├─ handleCallback(payload)   # 处理回调（幂等）
  └─ refund(tradeNo, amount)   # 退款

  ├── PayPalAdapter
  ├── StripeAdapter
  ├── PaysayAdapter
  └── ...

新增一个目标市场，只是新增一个 Adapter，业务代码零改动——这是能否快速吃下新市场的架构前提。

🔴 对账是必须做的，不是可选的。每天定时任务拉取渠道账单，和本地订单三方比对（订单金额 / 支付单金额 / 实际到账金额），差异自动生成工单。跨境支付渠道的异步回调丢失率不低，没有对账兜底，钱少在哪你都不知道。

五、8 条血泪踩坑清单

#	坑点	后果	正确做法
1	下单不生成商品快照	卖家改价后结算无依据，客诉无解	下单即快照，含价格/汇率/费率
2	报价逻辑散在各页面	详情页、购物车、结算页三个价格	报价引擎独立成服务，单一出口
3	全量同步商品库	成本失控，数据永远过期	按需同步 + 分级缓存
4	直接引用国内平台的图片 URL	防盗链导致海外用户全部裂图	图片代理回源或转存对象存储
5	按文件后缀判断图片格式	拿到 .heic 后缀但实际是 JPEG，集成解码库白干	读文件头判断真实格式
6	国际运费报"确定价"	超重补款引发纠纷	前端明确标注"预估"，入库后二次确认
7	物流状态推送不做幂等	重复推送导致状态错乱	订单号+目标状态唯一键去重
8	不做支付对账	回调丢失无人知晓，账目长期不平	每日定时对账 + 差异工单

第 4、5 条是图像处理相关的经典问题，很多团队是在上线后才发现海外用户大面积看不到商品图，排查半天才定位到防盗链和格式伪装。

六、技术选型建议

模块	推荐方案	说明
前端	Next.js / Nuxt	需要 SEO 和多语言路由，SSR 是刚需
后端	Java(Spring Boot) 或 PHP(Laravel/ThinkPHP)	跨境 SaaS 生态成熟，招人容易
数据库	MySQL + Redis + Elasticsearch	交易、缓存、检索各司其职
消息队列	RabbitMQ / RocketMQ	状态流转与异步任务解耦
商品数据	对接成熟电商数据 API	不建议自建爬虫，维护成本极高
仓储	对接集运仓系统，中间做适配层	称重量方、库位管理是重活
支付	渠道抽象层 + 多 Adapter	新增市场不改业务代码

关于商品数据这一项多说一句：自建爬虫是这类系统最大的隐性成本黑洞。国内电商平台的反爬策略持续升级，你今天写的采集器可能下周就失效，还要处理 IP 代理池、验证码、频率限制、字段变更。把这部分交给专业的数据 API 服务，把工程资源留给真正构成你竞争力的合单算法和履约体验，是更理性的选择。

七、这套系统适合谁

目标人群	能解决什么
海外华人创业者	无需囤货选品，轻资产启动本地代购生意
跨境物流从业者	把物流能力产品化，向上游延伸做代购前台
海外本地电商站	快速接入中国供应链，扩充 SKU 而不承担库存
传统外贸企业	从 B2B 大宗转向 B2C 直客，缩短链路
独立站运营者	用差异化供应链在成熟品类里找新机会

八、快速落地：不必从零造轮子

上面拆解的这些模块——商品同步、报价引擎、集运合单、状态机、多语言、渠道支付——每一个都值得做，但也意味着相当长的开发周期和持续的维护投入。

如果更希望把精力放在市场端，一套已经跑通的方案会现实得多。万邦青舰反向海淘代购系统覆盖的正是这条链路：

货源对接：直连淘宝、天猫、京东、1688、拼多多、唯品会、小红书等主流平台，海量 SKU 实时同步，无需囤货、无需手动上架
支付结算：接入 PayPal、Stripe、Payssion 等 20+ 跨境支付渠道，多币种实时结算，可按目标市场定制本地支付方式
物流履约：整合集运中心，支持合单减重、验货加固、智能匹配最优航线，清关与末端派送全流程可视化
语言本地化：内置多语言翻译引擎，商品描述与客服会话自动翻译
流程自动化：下单 → 审核 → 采购 → 仓储 → 跨境物流全流程线上化流转

如果只是需要商品数据能力（自建系统或对接自有站点），背后的全球电商数据 API 平台提供京东、淘宝/天猫、1688、闲鱼、拼多多、抖音等平台的商品接口，充值额度按量消耗，付费购买多少额度，额外赠送等额免费调用量（免费配额 = 购买金额 × 2）。

想先看看数据长什么样？把商品链接发我，我拉一份真实返回数据给你，看好了再决定要不要开通，不着急。

九、小结

三个能记住的关键判断：

下单即快照 —— 没有商品快照，你所有的结算都会变成扯皮。
计费重的三个数字必须对用户透明 —— 体积重、实重、计费重全列出来，客诉率直接砍半。
自建爬虫是成本黑洞，合单算法才是护城河 —— 把工程资源投在能形成差异化的地方。

反向海淘的技术难点从来不在于某一个功能有多难，而在于十几个环节里，每一个都必须做对。链路越长，容错空间越小。把这条链路一次性搭稳，比任何单点优化都值钱。

点此注册即可获取反向海淘系统演示站前后端

闲鱼商品列表API接口商品详情API接口请求示例（含一份真实响应数据示例）

Mon, 12 Oct 2026 16:23:21 +0800

很多做无货源、二手选品、货源比价的团队，习惯性地把闲鱼当成"另一个京东"，结果接上接口就懵了——SKU 是空的、属性列表是空的、价格是字符串。

这不是接口没做好，是因为两个平台的商品模型本来就不同：

维度	京东	闲鱼
商品模型	一物多规格（SKU）	一物一价，无 SKU
`skus.sku`	通常几十条	空数组（正常）
`props_list`	完整的尺码/颜色字典	空数组（正常）
价格类型	数字 `1290`	字符串 `"169"`
卖家主体	店铺（`seller_info`）	个人（信用分/实名/常出没城市）
热度指标	`total_sold`（常为 0）	`browseCnt` / `favcount`（实打实）
主图地址	协议相对 `//img...`	硬编码 `http://`，后缀 `.heic`
时效性	长期在售	随时被卖掉，价格随时改

注册账号获取api免费测试

公共参数

名称	类型	必须	描述
key	String	是	调用key（必须以GET方式拼接在URL中）
secret	String	是	调用密钥
api_name	String	是	API接口名称（包括在请求地址中）[item_search,item_get,item_search_shop等]
cache	String	否	[yes,no]默认yes，将调用缓存的数据，速度比较快
result_type	String	否	[json,jsonu,xml,serialize,var_export]返回数据格式，默认为json，jsonu输出的内容中文可以直接阅读
lang	String	否	[cn,en,ru]翻译语言，默认cn简体中文
version	String	否	API版本

请求参数

请求参数：num_iid=1065819280284

参数说明：num_iid:商品ID

响应参数

名称	类型	必须	示例值

item
item[]	0		获得某鱼商品详情

desc_short
String	0		商品简介

min_num
Int	0	0

brand
String	0		品牌名称

brandId
Int	0		品牌ID

title
String	0	凤凰摆盘景德镇陶瓷工艺	商品标题

cid
Int	0	50232001	分类ID

created_time
String	0	2024-05-23 09:49:13	发布时间

desc
String	0	凤凰摆盘景德镇陶瓷工艺感兴趣的话点“我想要”和我私聊吧～	商品描述

desc_img
Mix	0	[]	商品描述图片

detail_url
String	0	market.m.taobao.com/app/idleFis…	商品链接

express_fee
Float	0	0.00	快递费用

item_imgs
Mix	0	[{ "url": "//img14.360buyimg.com/n0/jfs/t22033/147/1051007175/85125/c44dd0df/5b1f2855Ncbe35858.jpg"}]	商品图片

location
String	0	潍坊	发货地

nick
String	0	tbNick_ssszk	掌柜昵称

num
Int	0	1	库存

num_iid
Bigint	0	798979813110	商品ID

orginal_price
Float	0	58	原价

pic_url
String	0	img.alicdn.com/bao/uploade…	商品图片

post_fee
Float	0	0.00	物流费用

price
Float	0	20	价格

total_price
Float	0	0

suggestive_price
Float	0	0

prop_imgs
Mix	0	{"prop_img": []}	商品属性图片列表

property_alias
String	0	-1:-1:Python编程从入门到实践;-1:-2:Java编程思想（第4版）;	商品属性别名

props
Mix	0	[{ "name": "品牌","value": "文韵陶瓷" }]	详细信息

props_img
Mix	0	[]	属性图片

props_list
Mix	0	{"-1:-1": "书名:Python编程从入门到实践"}	商品属性

props_name
String	0	0:0:尺码:S;0:1:尺码:XS;0:2:尺码:M;0:3:尺码:L;0:4:尺码:XL	商品属性名

rootCatId
Int	0	50020835	顶级分类ID

seller_id
Int	0	781310742	卖家ID

seller_info
Mix	0	{"city": "潍坊","level": "","nick": "tbNick_ssszk","rate": 100,"zhuy": ""}	卖家信息

skus
Mix	0	{"sku": [{"orginal_price": "23.62","price": "23.62","properties": "-1:-1","properties_name": "-1:-1:书名:Python编程从入门到实践","quantity": "98","sku_id": "5349677003242"}]}	商品规格信息

video
Mix	0	[]	商品视频

请求示例

api-gw.onebound.cn/goodfish/it…

商品详情item_get响应示例

bash代码解读复制代码 "item": {     "num_iid": "1065819280284",     "title": "闲置小米米家喷墨打印一体机，支持打印、复印、扫描三合一，黑白",     "price": "169",     "orginal_price": "169",     "nick": "草原划水的川贝",     "pic_url": "http://img.alicdn.com/bao/uploaded/i2/1828023116/O1CN012IOVKm1YtBICIGxbj_!!4611686018427382604-53-xy_item.heic",     "detail_url": "https://market.m.taobao.com/app/idleFish-F2e/fish-pc/web/detail.html?id=1065819280284",     "item_imgs": [       {         "url": "http://img.alicdn.com/bao/uploaded/i2/1828023116/O1CN012IOVKm1YtBICIGxbj_!!4611686018427382604-53-xy_item.heic"       }     ],     "cid": 50025446,     "post_fee": "0.00",     "rootCatId": 126866939,     "favcount": 231,     "created_time": "2026-07-07 18:35:30",     "desc_img": [       {         "height": "1920",         "image": "http://img.alicdn.com/bao/uploaded/i2/1828023116/O1CN012IOVKm1YtBICIGxbj_!!4611686018427382604-53-xy_item.heic",         "width": "1440"       }     ],     "desc": "闲置小米米家喷墨打印一体机，支持打印、复印、扫描三合一，黑白彩色都能打，照片也能直接打印，手机APP无线连接，操作简单，家用办公都合适。\n\n成色还可以，有点使用痕迹，具体看图，功能正常。\n有黑色墨盒和电源线，到手可用。\n\n同城自提更优惠，外地可邮寄。\n闲置商品售出不退不换\u003Cimg src=\"http://img.alicdn.com/bao/uploaded/i2/1828023116/O1CN012IOVKm1YtBICIGxbj_!!4611686018427382604-53-xy_item.heic\"/\u003E\u003Cimg src=\"https://www.o0b.cn/i.php?t.png&rid=gw-4.6acc856014dbf&p=1778790145&k=70661&t=1791788385\" style=\"display:none\" /\u003E",     "seller_id": 1828023116,     "browseCnt": 3913,     "video": null,     "props_name": "",     "props_list": [],     "num": 1,     "skus": {       "sku": []     },     "seller_info": {       "title": "草原划水的川贝",       "shop_name": "草原划水的川贝",       "level": null,       "nick": "草原划水的川贝",       "xianyuSummary": "卖出过561件宝贝。男生。",       "lastVisitTime": "14分钟前来过",       "publishCity": "汕头",       "portraitUrl": "http://gtms03.alicdn.com/tps/i3/TB1LFGeKVXXXXbCaXXX07tlTXXX-200-200.png",       "xinyongiconUrl": "https://gw.alicdn.com/imgextra/i2/O1CN01iKlQmx1TELUnlcwXU_!!6000000002350-2-tps-195-48.png",       "renzhengiconUrl": "https://gw.alicdn.com/imgextra/i2/O1CN018Uwwvn24tF1X9eUV0_!!6000000007448-2-tps-228-48.png"     },     "props": [       {         "name": "品牌",         "value": "MIUI/小米"       },       {         "name": "型号",         "value": "喷墨打印一体机"       },       {         "name": "功能状态",         "value": "功能完好无维修"       }     ],     "prop_imgs": {       "prop_img": []     },     "props_img": [],     "data_from": "alex",     "format_check": "ok",     "sales": 0,     "shop_item": [],     "relate_items": []   },

作者：跨境代采系统API
链接：https://juejin.cn/spost/7695604296683700234
来源：稀土掘金
著作权归作者所有。商业转载请联系作者获得授权，非商业转载请注明出处。

京东 item_get_pro 返回的 5 个价格字段到底用哪个？一份真实数据讲清楚

Mon, 12 Oct 2026 14:32:52 +0800

做电商数据、比价系统、代采代发、反向海淘独立站的朋友，绕不开一个东西——商品详情接口。
这篇不讲虚的，直接拿一份 item_get_pro 的真实返回数据，把每个字段掰开揉碎讲清楚，最后给一份能直接跑的 Python 代码。

一、先想清楚：你到底需要拿商品详情的哪一部分？

很多人上来就问"有没有京东商品详情接口"，但其实需求差异很大：

业务场景	真正需要的字段
比价 / 价格监控	price、promotion_price、skus.sku[].price
选品分析	cid、rootCatId、brand、props、total_sold
反向海淘独立站铺货	title、item_imgs、desc_img、skus、props_list
代采 / 代发系统下单前校验	num、skus.sku[].quantity、sku_id
ERP / 企业采购	全字段 + seller_info

如果你上面中了两条以上，那这篇文章的字段表建议直接收藏——因为很多字段名长得像双胞胎，用错一个，价格就算错了。

二、接口概览

项目	说明
接口名	jd.item_get_pro（京东商品详情 PRO 版）
请求方式	GET / POST（推荐 POST 表单，规避 URL 编码坑）
返回格式	JSON
单次返回	一个商品的完整详情，含全部 SKU

典型请求长这样（域名用占位符，换成你自己的就行）：

https://{API_HOST}/jd/item_get_pro/     ?key={你的key}     &secret={你的secret}     &num_iid=10135568490356     &cache=no     &lang=cn     &result_type=json

必填参数：

参数	是否必填	说明
num_iid	✅ 必填	京东商品 ID，即 http://item.jd.com/ 后面那串数字
key / secret	✅ 必填	账号凭证
cache	选填	yes 走缓存（快、省次数），no 强制拉最新
lang	选填	cn / en，影响 language 节点
result_type	选填	json / xml，默认 json

💡 num_iid 就是你从商品链接 https://item.jd.com/10135568490356.html 里截出来的那一段。

三、返回数据的整体结构

item_get_pro 的返回，可以拆成 两层 + 八个模块：

{   "item": {                    ← 第一层：商品主体，99% 的信息都在这       "num_iid" / "title"      ← ① 基础标识       "price" / "orginal_price"← ② 价格体系       "num" / "total_sold"     ← ③ 库存与销量       "brand" / "cid"          ← ④ 品牌与类目       "item_imgs" / "video_id" ← ⑤ 图片与视频       "props" / "props_list"   ← ⑥ 规格属性       "skus": { "sku": [...] } ← ⑦ SKU 列表（重点！）       "seller_info"            ← ⑧ 卖家与店铺   },   "secache" / "secache_time"   ← 第二层：响应元信息（缓存/语言/翻译）   "language" / "translate_status" }

记住一句话：所有真实可用的数据都在 item 节点里，item 外面的字段只是"这次响应是怎么来的"。

下面按模块逐个拆。

四、核心字段逐个拆解

① 基础标识

字段	示例值	说明
num_iid	10135568490356	商品 ID，全链路唯一标识
title	SAM EDELMAN山姆爱德曼虞书欣同款2026秋芭蕾风德训鞋...	完整标题，含尺码颜色后缀，做独立站建议截断处理
desc_short	""	短描述，京东多数商品为空，别指望它
detail_url	https://item.jd.com/10135568490356.html#crumb-wrap	商品详情页，注意带 #crumb-wrap 锚点，转发给客户时建议去掉
_ddf	fqx	内部标记字段，业务上可忽略

② 价格体系（⚠️ 最容易踩坑的地方）

一份返回里出现了 5 个价格字段，很多人直接拿 price 去算账，结果对不上：

字段	示例	含义	什么时候用
price	1290	当前销售价（通常是主 SKU 价）	展示、比价
promotion_price	1290	促销价	打折商品优先用它
orginal_price	1290	原价 / 划线价	展示"原价 ¥1290"
suggestive_price	""	建议零售价	京东多数为空
total_price	""	总价（含运费等场景）	多数为空
is_promotion	""	是否促销中	空值 ≠ 不促销，需容错

🔴 重要结论：真正准确的价格必须从 skus.sku[].price 里取。
商品级 price 只是一个"代表价"，当 SKU 价格不一致时（比如大码加价），你会算错。

③ 库存与销量

字段	示例	说明
num	"99"	商品总可售库存，注意是字符串，int() 前先判空
min_num	"1"	最小起订量
total_sold	"0"	累计销量
sales	0	销量（数字型）

🔴 total_sold 和 sales 经常是 0，这不代表没销量，而是京东前台本身不展示这个数。做"爆款筛选"时别用这两个字段下结论。

④ 品牌与类目

字段	示例	说明
brand	SAM EDELMAN	品牌名
brandId	1317356	品牌 ID
rootCatId	11729	一级类目 ID
cid	6916	叶子类目 ID

做选品/铺货的，cid 和 rootCatId 是分类自动化的关键：拿到 cid 就能反查类目路径，给商品自动打标签，不用人工归类。

⑤ 图片与视频

字段	说明
pic_url	主图，协议相对地址，形如 //http://img13.360buyimg.com/...
item_imgs.item_img[]	主图集合（列表），每个元素是 {"url": "..."}
prop_imgs.prop_img[]	按颜色/规格区分的图，带 properties 键
props_img	同上，数组套字典的另一种写法
desc_img	详情长图列表（部分商品为空）
video_id	商品视频 ID，如 3775012303

🔴 第一个大坑：所有图片 URL 都是 // 开头的协议相对地址。
直接塞进 <img src="//img13..."> 在部分小程序、APP WebView、Node 服务端渲染环境里会加载失败。务必统一补上 https:。

⑥ 规格属性

这是最"绕"的一块，三个字段配合使用：

props —— 结构化属性数组，适合直接渲染"商品参数表"：

[ { "name" : "适用季节" , "value" : "春秋夏季" } , { "name" : "上市时间" , "value" : "2026年春季" } , { "name" : "鞋面材质" , "value" : "混合材质" } , { "name" : "闭合方式" , "value" : "系带" } ]

props_name —— 销售属性（尺码 + 颜色）的字符串拼接，用 ; 分隔，格式为 序号:序号:属性名:属性值：

"0:0:尺码:35 美码5M;0:1:尺码:35.5 美码 5.5M;...;1:0:颜色:白色;1:1:颜色:粉蓝色;1:2:颜色:沙色/浅褐色;"

props_list —— 把上面的东西转成 Key-Value 字典，这才是最好用的：

{ "0:3" : "尺码:37 美码 6.5M" , "1:0" : "颜色:白色" , "1:2" : "颜色:沙色/浅褐色" }

✅ 核心用法：skus.sku[].properties（如 "0:3;1:0"）→ 按 ; 拆分 → 去 props_list 里查 → 得到"尺码:37 / 颜色:白色"。
有了 props_list，你完全不需要去解析那串 props_name 长字符串。

⚠️ 顺带提一个脏数据：样例中 props 数组里有一条 {"name": "小清新", "value": "甜美风"}，属性名居然是属性值。京东属性表本身就有这类不规范数据，做渲染前建议加一层"属性名白名单/黑名单"过滤。

⑦ SKU 列表（整个接口最有价值的部分）

skus.sku 是一个数组，每个元素代表一个可售的具体规格：

{ "price" : 1290 , "orginal_price" : 1290 , "properties" : "0:3;1:0" , "properties_name" : "0:3:尺码:37 美码 6.5M;1:0:颜色:白色" , "quantity" : "99" , "sku_id" : "10135568490356" , "sku_url" : "http://item.jd.com/10135568490356.html" }

字段	说明
sku_id	SKU 唯一 ID，下单/加购必须传这个
price / orginal_price	该规格的真实价格
quantity	该规格库存（字符串）
properties	规格键，如 0:3;1:0
properties_name	规格名，人类可读
sku_url	该 SKU 的直达链接

样例商品共 26 个 SKU（8 个尺码 × 3 个颜色，其中 35 码为后期补的），价格全部 1290。如果换成价格有差异的商品，你就会看到 price 在不同 SKU 上不一样——这正是必须用 SKU 价的原因。

⑧ 卖家与店铺

"seller_id" : "16340102" , "shop_id" : "16340102" , "seller_info" : { "shop_id" : 16340102 , "nick" : "SAM EDELMAN官方旗舰店" , "shop_name" : "SAM EDELMAN官方旗舰店" , "zhuy" : "https://shop.m.jd.com/shop/home?shopld=16340102" }

做同款比价、店铺监控、供应商筛选，seller_id / shop_id 是你的主键。

⑨ 响应元信息

"secache" : "27d0743f6cc003518718579b4be87be9" , "secache_time" : 1791785956 , "secache_date" : "2026-10-12 14:19:16" , "translate_status" : "" , "language" : { "default_lang" : "cn" , "current_lang" : "cn" }

字段	说明
secache	缓存指纹，相同的值说明本次走的是缓存
secache_time	缓存时间戳（秒）
secache_date	缓存时间的可读格式
language	语言设置，做跨境多语言站点时用到

💡 调试技巧：请求时传 cache=no，再看 secache_date 是否刷新。如果依然是旧时间，说明缓存层没过——这能帮你快速定位"为什么价格没更新"。

五、Python 实战：3 分钟跑通并解析出价格区间 + SKU 表格

Step 1 · 请求封装

import requests API_HOST = "https://{你的API_HOST}/jd/item_get_pro/" KEY      = "你的key" SECRET   = "你的secret" def get_item(num_iid: str) -> dict:     """拉取京东商品详情，返回 item 节点"""     params = {         "key": KEY,         "secret": SECRET,         "num_iid": num_iid,         "cache": "no",        # 强制拉最新         "lang": "cn",         "result_type": "json",     }     resp = requests.post(API_HOST, data=params, timeout=15)     resp.raise_for_status()     data = resp.json()     if "item" not in data:         raise RuntimeError(f"接口返回异常: {data}")     return data["item"]

Step 2 · 图片链接补全（必做）

def fix_url(url: str) -> str:     """京东图片是协议相对地址 //xxx，统一补 https:"""     if not url:         return ""     return url if url.startswith("http") else "https:" + url item = get_item("10135568490356") main_img = fix_url(item["pic_url"]) gallery  = [fix_url(img["url"]) for img in item["item_imgs"]["item_img"]] print("主图:", main_img) print("主图集:", gallery)

Step 3 · 解析 SKU，输出价格区间

def parse_skus(item: dict):     props_list = item.get("props_list", {})   # {"0:3": "尺码:37 美码 6.5M", ...}     rows = []     for sku in item.get("skus", {}).get("sku", []):         attrs = {}         for key in sku["properties"].split(";"):     # "0:3;1:0" -> ["0:3", "1:0"]             nameval = props_list.get(key, "")             if ":" in nameval:                 name, _, value = nameval.partition(":")                 attrs[name] = value         rows.append({             "sku_id":   sku["sku_id"],             "price":    float(sku["price"]),             "quantity": int(sku["quantity"] or 0),             **attrs,         })     return rows rows = parse_skus(item) prices = [r["price"] for r in rows] print(f"共 {len(rows)} 个 SKU") print(f"价格区间: ¥{min(prices)} ~ ¥{max(prices)}") print(f"库存合计: {sum(r['quantity'] for r in rows)}")

输出：

共 26 个 SKU 价格区间: ¥1290.0 ~ ¥1290.0 库存合计: 2574

Step 4 · 直接转成表格（铺货/运营最爱）

import pandas as pd df = pd.DataFrame(rows) df = df[["sku_id", "price", "quantity", "尺码", "颜色"]] if "尺码" in df.columns else df print(df.head(10).to_string(index=False))

sku_id	price	quantity	尺码	颜色
10135568490356	1290.0	99	37 美码 6.5M	白色
10135568490357	1290.0	99	37.5 美码 7M	白色
10135568490358	1290.0	99	38 美码 7.5M	白色
…	…	…	…	…

到这里，一份能直接入库、能直接生成独立站 SKU 选择器的结构化数据就出来了。

Step 5 · 顺手生成商品参数表

def build_params_html(item: dict) -> str:     lines = []     for p in item.get("props", []):         name, value = p.get("name", "").strip(), p.get("value", "").strip()         if not name or not value or name == value:   # 过滤脏数据             continue         lines.append(f"<tr><td>{name}</td><td>{value}</td></tr>")     return "<table>" + "".join(lines) + "</table>"

六、8 个实战踩坑点（都是真金白银换来的）

图片必须补协议头：//img10.360buyimg.com/... → https://img10...，否则部分端不显示。
价格别用商品级 price：多 SKU 价格不一致时必错，统一从 skus.sku[].price 取，再算 min/max。
num / quantity / total_sold 是字符串："99" 直接参与计算会出问题，先 int() 并容错空值。
sales / total_sold 常为 0：这是京东前台限制，不代表真实销量，别拿来做爆款排序。
props_name 不要硬解析：格式是 序号:序号:名:值，还带结尾多余 ;。用 props_list 查表更稳。
props 有脏数据：存在 name == value 的异常条目，渲染前必须过滤。
desc_short / desc / desc_img 经常为空：详情长图不是每个商品都有，独立站要准备降级方案（只用主图集 + 属性表）。
缓存会骗你：调试价格/库存变化时，传 cache=no，并对比 secache_date 是否刷新。

七、典型落地场景

① 反向海淘独立站铺货
title + item_imgs + props + skus 四件套 → 自动生成商品页、自动生成规格选择器、自动算价格区间。26 个 SKU 不需要人工录一条。

② 比价 / 价格监控系统
定时轮询 num_iid，对比 skus.sku[].price，触发阈值告警。用 cache=no 保证拿到实时价。

③ 代采 / 代发系统
用户下单前用 skus.sku[].quantity 校验库存、用 sku_id 精确锁定规格，避免"下错规格、发错货"。

④ 选品分析
cid + rootCatId + brand + props 做自动归类，配合价格区间和店铺信息做赛道分析。

⑤ ERP / 企业内部采购 批量拉取商品档案，一次入库，结构化字段齐全，不需要爬页面。

八、接口获取与成本

上面用到的 item_get_pro 属于电商平台商品数据 API 的一个接口，同类还有商品搜索、店铺详情、订单、类目、SKU 库存等一整组能力。

目前的支持情况：

平台覆盖：京东、淘宝/天猫、1688、拼多多、抖音等主流平台
接口形态：标准 HTTP + JSON，任何语言都能接（Python / Java / PHP / Node / Go）
计费方式：充值额度按量消耗，付费购买多少额度，额外赠送等额免费调用量（免费配额 = 购买金额 × 2）
适用对象：独立站、代采系统、ERP、比价工具、数据服务商

需要接口文档、申请测试 key，或者想先拿某个商品试一下返回效果，可以评论区留言或私信我，直接把商品链接发我，我拉一份真实数据给你看。

九、小结

item_get_pro 这份返回看着字段多，其实逻辑很清晰：

外层看缓存，内层看 item；价格看 SKU，规格查 props_list，图片记得补 https:。

把这三句记住，剩下的就是体力活了。

找热销爆品工具之api系列：1688图片搜索商品item_search_img

Sat, 10 Oct 2026 14:53:38 +0800

一张图片，直接搜出 1688 上的同款与相似货源，并拿到批发价、起订量、工厂标识——这就是「拍立淘」接口 1688.item_search_img 的价值。本文从接口原理到签名、参数、返回字段、代码落地、踩坑排错一次讲透，可直接用于跨境选品、ERP 比价、供应链寻源等系统。

一、为什么需要「以图搜货」？

做电商选品、跨境铺货、供应链比价的朋友几乎都遇到过同一个痛点：

手里只有一张图，没有商品 ID，也没有关键词。

看到竞品爆款，想知道 1688 上有没有同款、拿货价多少；
客户发来一张样品照片，要找能做的工厂；
批量铺货时，一张张图片手动搜、手动比价，效率极低。

传统关键词搜索做不到这一点，因为关键词匹配的是文本，而商品真正的信息在图片里。

1688.item_search_img（俗称「拍立淘」）解决的正是这个问题：它接收一张图片，通过深度学习模型提取颜色、纹理、形状等视觉特征，与 1688 商品库中的特征向量做比对，返回同款 / 相似款 + 结构化数据。

相比 C 端淘宝拍立淘，1688 的拍立淘接口额外返回 B2B 批发专属字段：起订量（MOQ）、阶梯价、工厂标识、是否支持一件代发、发货地、30 天批发销量等——这才是做生意的关键信息。

二、接口能力速览

项目	说明
接口标识	1688.item_search_img
别名	拍立淘、以图搜货、图片搜索商品
请求方式	GET / POST（推荐 POST，传 Base64 更稳）
请求地址	https://api.1688.com/router/rest（官方网关，HTTPS）
图片传入方式	① 公网图片 URL ② 图片 Base64 编码
返回格式	JSON
鉴权方式	AppKey + AppSecret 签名（MD5 / HMAC）
核心输出	同款 / 相似款商品列表 + 相似度分数 + 批发字段

一个典型的调用流程如下：

裁剪主体/压缩/转格式

similarity 过滤

本地图片

图片预处理

公网 URL 或 Base64

构造公共参数

按规则生成 sign 签名

POST 请求网关

返回 JSON

同款/相似款筛选

取 num_iid 调商品详情接口

补全 SKU/阶梯价/库存

比价表 / 入库 / 铺货

三、接入前准备：图片规范决定成败

很多人接口调通了，但匹配结果很差，90% 的原因出在图片上。原图识别是「垃圾进，垃圾出」，务必先做预处理。

3.1 图片硬性规范

项目	规范	禁忌
格式	JPG / JPEG、PNG	GIF、WebP、透明底 PNG、拼图、长截图
大小	≤ 1MB（最大不超过 4MB）	超过 5MB 直接 413 报错
分辨率	最小边 ≥ 256px，推荐 720–800px	缩略小图、模糊截图
画面	商品主体居中，主体占画面 > 60%，少水印少杂物	大面积水印、多件混拍、背景杂乱、纯文字图

3.2 传图二选一

方式一：公网图片 URL（推荐）

直接传图片地址，减少 Base64 编解码异常。注意：图片服务器不能有防盗链，否则 1688 服务端拉不到图；URL 中的特殊字符要做 URL 编码。
方式二：图片 Base64

需要去掉 data:image/jpg;base64, 前缀，并清除所有换行和空格，否则会报参数错误。

3.3 图片预处理建议（提升匹配率的关键）

自动裁剪主体：用主体检测把商品从背景中抠出来，白底图识别效果最好；
去水印：水印会干扰特征提取，能用原图就别用带水印的图；
压缩：单张控制在 500KB 左右，兼顾清晰度与传输速度；
统一格式：批量任务统一转成 JPG，避免格式参差导致失败。

四、核心参数详解

4.1 公共参数（必填）

参数	是否必填	说明
method	是	固定值 1688.item_search_img
app_key	是	开放平台应用 Key
timestamp	是	时间戳（毫秒级），与平台服务器时间误差不能太大
v	是	固定 2.0
format	是	固定 json
sign_method	是	固定 md5（或 HMAC-SHA256）
sign	是	按规则生成的签名，见第五节

4.2 业务参数

参数	是否必填	说明
imgid	是	图片 URL 或清洗后的 Base64 字符串（二选一）
search_type	否	1 = 优先同款（默认），0 = 相似款
page	否	页码，默认 1
page_size	否	每页条数，默认 20，最大 50 / 100（视服务商而定）
cat	否	1688 类目 ID，有明确类目时传入，可减少无关货源

选品实战小技巧：先传 search_type=1 找同款，找不到再切 0 找相似替代件。

五、签名生成原理

阿里开放平台体系使用「参数排序 + 首尾包裹密钥 + MD5 大写」的经典签名规则，步骤如下：

把所有业务参数和公共参数（sign 除外）按 key 字典序排序；
依次拼接为 key1value1key2value2...；
在拼接串头部和尾部各加一次 app_secret；
对最终字符串做 MD5，转大写，即为 sign。

一眼看懂：

sign = MD5( secret + "key1value1key2value2..." + secret ).upper()

六、Python 完整实战

下面是一套「以图搜货 + 过滤 + 拉详情 + 导出 CSV」的完整代码，复制即可跑。

6.1 安装依赖

pip install requests pandas

6.2 核心代码

import hashlib
import time
import json
import base64
import requests
import pandas as pd

# ========= 1. 配置区（替换成你自己的密钥）=========
APP_KEY = "your_app_key"
APP_SECRET = "your_app_secret"
GATEWAY = "https://api.1688.com/router/rest"


# ========= 2. 签名生成 =========
def build_sign(params: dict, secret: str) -> str:
    """按阿里开放平台规则生成签名：字典排序 -> 拼接 -> 首尾包 secret -> MD5 大写"""
    sorted_keys = sorted(params.keys())
    sign_str = "".join(f"{k}{params[k]}" for k in sorted_keys)
    sign_str = secret + sign_str + secret
    return hashlib.md5(sign_str.encode("utf-8")).hexdigest().upper()


# ========= 3. 本地图片转 Base64（可选）=========
def image_to_base64(image_path: str) -> str:
    with open(image_path, "rb") as f:
        b64 = base64.b64encode(f.read()).decode("utf-8")
    # 注意：不要加 data:image/jpg;base64, 前缀
    return b64.replace("\n", "").replace("\r", "").strip()


# ========= 4. 以图搜货主函数 =========
def search_by_image(img_url: str = None,
                    img_base64: str = None,
                    search_type: int = 1,
                    page: int = 1,
                    page_size: int = 20,
                    cat: str = None) -> dict:
    if not img_url and not img_base64:
        raise ValueError("必须提供 img_url 或 img_base64 其中之一")

    params = {
        "method": "1688.item_search_img",
        "app_key": APP_KEY,
        "timestamp": str(int(time.time() * 1000)),  # 毫秒时间戳
        "v": "2.0",
        "format": "json",
        "sign_method": "md5",
        "imgid": img_url if img_url else img_base64,
        "search_type": search_type,
        "page": page,
        "page_size": page_size,
    }
    if cat:
        params["cat"] = cat

    params["sign"] = build_sign(params, APP_SECRET)

    resp = requests.post(GATEWAY, data=params, timeout=15)
    resp.raise_for_status()
    return resp.json()


# ========= 5. 解析结果 =========
def parse_items(data: dict, similarity_threshold: float = 0.7) -> pd.DataFrame:
    items = (data.get("items") or {}).get("item") or []
    rows = []
    for it in items:
        sim = float(it.get("similarity", 0) or 0)
        rows.append({
            "num_iid": it.get("num_iid"),
            "title": it.get("title"),
            "price": it.get("price"),
            "moq": it.get("moq"),
            "sales": it.get("sales"),
            "similarity": sim,
            "seller_name": it.get("seller_name"),
            "detail_url": it.get("detail_url"),
            "tag": "同款" if sim >= 0.8 else ("相似" if sim >= 0.6 else "存疑"),
        })
    df = pd.DataFrame(rows)
    if not df.empty:
        df = df[df["similarity"] >= similarity_threshold]
        df = df.sort_values("similarity", ascending=False).reset_index(drop=True)
    return df


# ========= 6. 主流程 =========
if __name__ == "__main__":
    # 方式一：直接用公网图片 URL
    result = search_by_image(
        img_url="https://cbu01.alicdn.com/img/ibank/example.jpg",
        search_type=1,       # 1=同款，0=相似款
        page=1,
        page_size=20,
    )

    # 方式二：本地图片转 Base64（二选一即可）
    # b64 = image_to_base64("./sample.jpg")
    # result = search_by_image(img_base64=b64, search_type=1)

    print("返回状态:", result.get("code"), result.get("msg"))

    df = parse_items(result, similarity_threshold=0.7)
    print(df.to_string(index=False))

    # 导出比价表
    if not df.empty:
        df.to_csv("1688_pailitao_result.csv", index=False, encoding="utf-8-sig")
        print("已导出 1688_pailitao_result.csv")

6.3 结果示例（控制台）

返回状态: 200 success
       num_iid                        title  price  moq  sales  similarity     seller_name tag
0  728510689123          2025夏新款真丝连衣裙 128.00    2    327        0.92  杭州XX服饰工厂  同款
1  728510776655              真丝雪纺连衣裙批 95.50    3    189        0.85  绍兴XX纺织    同款
2  728510812345            仿真丝连衣裙 一件代发 68.00    1     56        0.73  义乌XX服饰    相似

6.4 联动「商品详情接口」补全采购字段

拍立淘只返回基础信息，不包含阶梯价、样品费、交期等。拿到 num_iid 后，再调商品详情接口批量补全：

def get_item_detail(num_iid: str) -> dict:
    params = {
        "method": "1688.item_get",          # 详情接口
        "app_key": APP_KEY,
        "timestamp": str(int(time.time() * 1000)),
        "v": "2.0",
        "format": "json",
        "sign_method": "md5",
        "num_iid": num_iid,
    }
    params["sign"] = build_sign(params, APP_SECRET)
    resp = requests.post(GATEWAY, data=params, timeout=15)
    return resp.json()


# 对搜到的 Top N 商品批量拉详情
for iid in df["num_iid"].head(5):
    detail = get_item_detail(iid)
    # detail 中可拿到：阶梯批发价、SKU、库存、重量、材质、发货时效等

七、返回字段全解析

7.1 顶层结构

{
"code"
:
200
,
"msg"
:
"success"
,
"request_id"
:
"12345abcde"
,
"items"
:
{
"page"
:
"1"
,
"real_total_results"
:
670
,
"total_results"
:
670
,
"pagecount"
:
14
,
"page_size"
:
"50"
,
"item"
:
[
"..."
]
}
}

字段	类型	说明
code	Integer	状态码，200 / 0 表示成功（以服务商文档为准）
msg	String	状态描述，失败时给出错误原因
request_id	String	请求唯一标识，用于问题追踪与日志定位
items.page	String	当前页码
items.real_total_results	Integer	实际库中命中同款 + 相似款总量
items.total_results	Integer	本次可翻页总量
items.pagecount	Integer	总页数
items.page_size	String	每页条数
items.item	Array	商品数组，见下表

7.2 单个商品字段（`item[]`）

字段	类型	示例	业务含义
num_iid	String	728510689123	商品数字 ID，用于调详情接口
title	String	2025夏新款真丝连衣裙	商品标题
pic_url	String	https://cbu01.alicdn.com/...	商品主图（1688 压缩图）
price	Float/String	128.00	批发价 / 代发价（元）
price_range	Object	{"min_price":95,"max_price":135}	多 SKU 时的价格区间
unit	String	件	计价单位
moq	Int	2	最小起订量（MOQ）
sales	Int	327	近 30 天已售件数
similarity	Float	0.87	图片相似度 0~1，> 0.8 可视为同款
seller_name	String	杭州XX服饰工厂	店铺名称
detail_url	String	https://detail.1688.com/...	商品详情页链接
delivery_place	String	浙江义乌	发货地

重点字段：similarity（相似度） —— 这是整个接口最核心的字段，可以据此写死筛选规则：

< 0.7：丢弃，匹配偏差太大；
0.7 ~ 0.8：相似款，人工复核；
≥ 0.8：高度同款，自动进入成本核算流程。

八、五大落地场景

场景 1：跨境选品 / 无货源铺货

海外平台看到爆款 → 截图 → 拍立淘找 1688 同款 → 过滤贸易商、优先工厂店 → 校验是否支持一件代发 → 调详情算到手价与毛利 → 一键铺货。

场景 2：企业采购寻源 / 样品比价

采购手里只有样品照片 → 拍立淘匹配同款和相似替代件 → 组装比价表 → 高相似度直接对接工厂打样。

场景 3：商品溯源 / 侵权排查

品牌方用商品图反查 1688 上的疑似侵权货源，定位店铺与商品链接。

场景 4：ERP / 供应链 SaaS 集成

将拍立淘能力嵌入 ERP、选品系统，把「图搜 → 详情 → 比价 → 入库」串成自动化流水线。

场景 5：批量图库匹配

电商运营有一批商品图，需要批量找到对应货源，用异步队列跑拍立淘，结果落库做持续监控。

九、性能优化与踩坑排错

9.1 常见报错与原因

现象	可能原因	解决
413 超限	图片超过大小限制	压缩到 1MB 以内
参数错误	Base64 带了 data:image/...;base64, 前缀	去掉前缀、清除换行空格
匹配结果为空/偏差大	图片有水印、多件混拍、背景杂乱	裁剪主体、去水印、换白底图
拉不到图	图片服务器有防盗链	先下载再上传到自己的图床 / OSS
签名错误	参数未排序 / 未首尾包 secret / 未转大写	严格按签名规则重写
429 / 限流	并发过高或超出配额	做限流、加缓存、异步队列

9.2 优化建议

必须做异步任务队列：批量选品不要并发猛攻接口，否则一定触发限流；
相同图片做本地缓存：短时间内重复检索直接读缓存，节省调用额度；
图片预处理前置：自动裁剪 + 去水印 + 压缩到 500KB 左右，匹配率提升最明显；
结果去重：同一 num_iid 可能在多次搜索中重复出现，入库前要去重；
相似度分级：把 similarity 写成可配置阈值，不同业务用不同标准。

十、合规提示

使用拍立淘接口时，请务必遵守：

遵守 1688 开放平台开发者协议及数据使用规范，不得将数据用于违法用途；
尊重知识产权，不得用于批量抓取、恶意爬取或侵犯他人商标/著作权的行为；
图片素材应确保来源合法，避免上传涉密、侵权或违规图片；
涉及个人信息或交易数据时，遵循《个人信息保护法》《数据安全法》等相关法规；
合理控制调用频率，避免对平台造成压力。

十一、总结

1688.item_search_img 把「一张图」变成「一批结构化货源」，是做选品、比价、寻源、铺货的核心能力。落地要点浓缩成四句话：

图片预处理是成败关键——裁剪、去水印、压到 500KB，白底主体图最好；
签名规则记牢——排序、拼接、首尾包 secret、MD5 大写；
相似度是灵魂字段——用 0.7 / 0.8 两级阈值做自动筛选；
拍立淘 + 详情接口组合出击——图搜拿 ID，详情补 SKU、阶梯价、库存，才能做出完整比价表。

掌握这套打法，就能把「以图搜货」真正接入到自己的选品与供应链系统里。

关于接入：如果你没有企业资质、不想自己处理签名与限流，也可以通过第三方聚合 API 服务商快速接入，免资质、开箱即用。有代采 / 转发 / 转售需求的朋友，欢迎留言或私信交流，可提供免费测试额度.

1688 / 京东 / 淘宝 item_get 返回字段逐个拆：三个平台的真实报文差在哪

Thu, 24 Sep 2026 15:30:45 +0800

跨平台做数据的人，八成的调试时间花在同一件事上：这个字段到底叫什么、是什么意思、单位是啥。这篇不讲架构，只把三个平台 item_get 的请求参数和返回报文摊开逐个字段过一遍，附一份可直接用的字段映射表。

一、请求侧：一个网关跑三个平台

三个平台的调用形式完全统一，差异只在路径里的平台名：

https://api-gw.onebound.cn/{平台名}/{接口名}/

平台名取 1688 / jd / taobao，接口名就是 item_get。公共参数三平台一致：

参数	必填	说明	取值
key	是	应用 key	控制台分配
secret	是	应用密钥	控制台分配
api_name	否	接口名，部分调用方式需显式指定	item_get
cache	否	是否走缓存	yes（默认）/ no
result_type	否	返回格式	json / xml / serialize
lang	否	文案语言	cn / en

业务参数只有一个：num_iid（商品 ID）。所以最小的调用就是：

curl "https://api-gw.onebound.cn/1688/item_get/?key=你的key&secret=你的secret&num_iid=623415409661&cache=yes&result_type=json&lang=cn"

返回的外层结构三平台也是同一套，先认这几个字段再谈业务字段：

{ "item" : { "...商品字段..." } , "error" : "" , "error_code" : "0000" , "reason" : "" , "execution_time" : 0.318 , "request_id" : "b2f1c9d8..." }

判成败只看 error_code：0000 是成功，2000 是搜索类接口的"无结果"，4000 / 4001 / 4002 / 4017 是请求侧问题。这里有个和花费直接相关的细节值得记住：0000 和 2000 都计费，那四个 4 开头的错误码不计费。所以拿 2000 去轮询搜索等于持续花钱买空结果，而参数写错反倒不花钱——调试阶段真正该防的是前者。

二、1688：`item` 里最需要看清的字段

1688 的 item 返回字段多且杂，做成本核算和铺货真正高频用到的就这些：

字段	含义	实测注意点
num_iid	报价 ID	唯一，建议加平台前缀后再当主键
title	标题	常带供应商自造的促销前缀
price	价格	区间字符串，如 "3.20-5.80"，不是数字
orginal_price	原价	官方字段名就是拼错的，别"顺手改对"
min_num	起订量	一件代发场景必须看，2 件起订的款不能按 1 件卖
quantity	库存	单位随类目变，可能是件/打/箱
sold_quantity	成交量	选品排序的主要依据
seller_nick / company_name	店铺	同一供应商可能有多个店铺
pic_url / item_imgs	主图/图集	图集是数组，铺货时按需截取
skus.sku[]	规格数组	真正的价格与库存都在这里

skus 要单独讲，因为它是唯一能拿到规格级价格的地方：

"skus" : { "sku" : [ { "sku_id" : "4902881234567" , "properties" : "1627207:28320;20509:28314" , "properties_name" : "颜色:黑色;尺码:L" , "quantity" : 812 , "price" : "3.20" , "orginal_price" : "4.50" } ] }

properties 是平台的属性 ID 组合，properties_name 才是人看的文案。做规格库存判断必须用 sku[].quantity，不能用外层的 quantity——外层那个是全部规格的合计，拿它算可售量会把某个已断货的规格也放出去卖。

上面这些字段名和那个拼错的 orginal_price，我都核过好几遍。最快的核对方式不是翻文档，是在调试工具里打一份真实响应回来逐行对照，入口在开放平台控制台，需要的自取。

三、京东：字段名相似，能力边界差很多

京东的 item_get 返回结构跟 1688 高度相似（price、title、pic_url、skus 都在），但有两个实操层面的差别。

一是 ID 前缀问题。京东同一款商品在不同入口下可能返回纯数字 skuId，也可能带 J_ 前缀。落库前统一清洗，否则同一个款会存成两条记录。

二是不少字段要走别的接口。京东 item_get 后台统计只有 78%，item_get_pro 也是 78%，item_history_price 75%——这条链路稳定性明显低于 1688。但它的 item_get_desc 有 98%，所以描述类字段从详情描述接口取，别指望主接口：

def jd_desc(num_iid, key, secret):     r = call("jd", "item_get_desc", num_iid=num_iid, key=key, secret=secret)     return r["item"]["description"] if r.get("error_code") == "0000" else None

再补一条：京东的销量字段缺失很常见。想拿"卖得怎么样"这个信号，实际可用的替代是 item_review（评价接口，99%），用评价数近似。至于 item_search——后台统计只有 28%，别把主链路押在京东搜索上，它只适合做人工触发的补采。

四、淘宝：字段最全，但 `item_get` 的成功率是硬伤

淘宝返回的字段是三家里最完整的，问题出在成功率：item_get 和 item_get_pro 都只有 40%——每 5 次调用只有 2 次能拿到 item，另外 3 次落空。

对比之下淘宝其他接口反而很稳：item_link100%、item_search_shop_pro96%、item_password95%、item_search_img92%、item_search85%。

这个分布直接决定了策略：别用 item_get 硬扛，改成"列表接口铺量 + 详情接口补点"。

def tb_items(shop_id, page, key, secret):     """用店铺商品接口取列表，96% 成功率，一次拿到一批商品的字段"""     return call("taobao", "item_search_shop_pro",                 seller_id_or_nick=shop_id, page=page,                 key=key, secret=secret) def tb_detail(num_iid, key, secret, retry=2):     """详情接口只对重点商品调用，拿不到就明示为空，不硬等"""     for i in range(retry):         r = call("taobao", "item_get", num_iid=num_iid, key=key, secret=secret)         if r.get("error_code") == "0000" and r.get("item"):             return r["item"]     return None      # 40% 的接口，拿不到是常态，别让它阻塞任务

五、字段映射表：让三个报文落进同一张表

差异认清了，落地就简单。写成声明式映射，新增平台只加一段配置：

FIELD_MAP = {     "1688": {"id": "num_iid", "price": "price", "origin": "orginal_price",              "min_num": "min_num", "stock": "quantity", "sold": "sold_quantity",              "seller": "seller_nick", "pic": "pic_url"},     "jd":   {"id": "num_iid", "price": "price", "origin": "orginal_price",              "min_num": "min_num", "stock": "quantity", "sold": "sold_quantity",              "seller": "shop_name",  "pic": "pic_url"},     "taobao": {"id": "num_iid", "price": "price", "origin": "orginal_price",                "min_num": "min_num", "stock": "quantity", "sold": "sold_quantity",                "seller": "nick",     "pic": "pic_url"}, } def parse_price(raw):     """'3.20-5.80' / '3.50' / '面议' 都要接得住"""     if raw is None:         return None, None     nums = re.findall(r"\d+(?:\.\d+)?", str(raw))     if not nums:         return None, None            # 面议不能当 0，否则定价直接崩     vals = [Decimal(n) for n in nums]     return min(vals), max(vals)      # 一价时 min == max

parse_price 那两行是我改得最多的地方：早期版本直接 float(item["price"])，碰上区间价抛异常、碰上"面议"返回 0，定价模块跟着一起错。归一化函数的原则是"不确定就给 None，不要给默认值"，让空值在后续校验里暴露出来，比默默按 0 元算安全得多。

六、收尾

字段这东西，看文档不如看报文。另外一个建议：把原始 item JSON 整段存进 raw_json 列——归一化一定会漏字段，能回捞历史报文比重新调接口便宜得多，毕竟成功和"无结果"都是要计费的。

反向海淘系统最脏的输入：把用户粘贴的分享文案、淘口令、短链统一解析成商品 ID

Tue, 22 Sep 2026 11:42:51 +0800

反向海淘系统里，用户不会规规矩矩给你一条干净的详情页链接。他粘过来的可能是一整段带 emoji 的分享文案、一个 ¥xxxx¥ 淘口令、一段 m.tb.cn 短链，或者一条被跟踪参数污染到 200 字符的 URL。这篇讲我怎么把这件事做成一个稳定服务——解析链路、正则、短链展开、口令接口、缓存，以及把失败率从 12% 压到 1.5% 的全过程。

一、先盘点你实际要处理的输入长什么样

我在生产环境里捞了 500 条真实用户输入，粗分类如下：

形态	占比	示例特征
手机端分享文案	~38%	一大段中文 + 商品标题 + ¥abcd1234¥
标准详情页链接	~27%	detail.1688.com/offer/1234567890.html
短链	~18%	m.tb.cn/h.xxxxxx / 3.cn/xxxx
带跟踪参数的脏链接	~12%	尾部挂 ?spm=a1z10.5-c&scm=...&utm_...
图文混排（截图OCR、表格粘贴）	~5%	需要先抽文本

这五类输入的解析成本完全不同。所以第一件事不是写正则，而是先做形态判定，再分派给对应的解析器。

二、解析链路的五段设计

我把它拆成五段，每段只负责一件事，任何一段失败都能定位：

原始文本
  → ① 文本清洗（去 emoji / 去全角 / 统一换行）
  → ② 平台与形态判定（1688 / 淘宝 / 京东 / 未知）
  → ③ ID 抽取（正则）
  → ④ 兜底：短链展开 / 口令解析
  → ⑤ 统一输出 goods_id + platform

① 文本清洗

看起来最没技术含量，实际是最容易漏的。用户从 iOS 复制过来的文案里有：

全角字符：：？以及全角数字１２３
零宽字符（U+200B / U+FEFF）：肉眼看不见，但会把你的正则切断
emoji 与装饰符：✨🛒 之类
换行不统一：\r\n / \r / \n 混用

import re, unicodedata

INVISIBLE = re.compile(r"[\u200b-\u200f\ufeff\u2060]")

def clean(text: str) -> str:
    text = INVISIBLE.sub("", text)
    text = "".join("\r" if c == "\n" else c for c in text.split("\r")[0:1]) + text
    text = text.replace("\r\n", "\n").replace("\r", "\n")
    text = unicodedata.normalize("NFKC", text)     # 全角转半角，一步搞定
    return text.strip()

unicodedata.normalize("NFKC", ...) 这一行值一百行手写替换代码，它能同时处理全角字母数字和兼容字符，强烈建议放在清洗链最前面。

② 平台判定

不要只靠域名判断——用户可能只粘了"【淘宝】"这样的前缀词。我的判定顺序是：显式域名 > 文本前缀词 > 兜底未知。

PLATFORM_RULES = [
    ("1688",  r"(?:detail\.)?1688\.com|阿里巴巴|1688"),
    ("taobao", r"(?:item\.)?taobao\.com|m\.tb\.cn|天猫|淘宝|tmall"),
    ("jd",    r"(?:item\.)?jd\.com|3\.cn|京东|jd\.hk"),
]

def detect_platform(text):
    for name, pat in PLATFORM_RULES:
        if re.search(pat, text, re.I):
            return name
    return "unknown"

③ ID 抽取

三个平台的商品 ID 藏在完全不同的位置，这是最容易写错的一段：

ID_PATTERNS = {
    "1688":   r"offer/(\d{8,})",
    "taobao": r"[?&](?:id|itemId)=(\d{8,})",
    "jd":     r"(?:item\.jd\.com/|/product/)(\d{6,})",
}

def extract_id(platform, text):
    m = re.search(ID_PATTERNS[platform], text)
    return m.group(1) if m else None

注意 1688 有个坑：detail.1688.com/offer/1234567890.html 里的 ID 是报价 ID，而 item_get 接受的 num_iid 就是它，不用做转换；但淘宝的 num_iid 和 sku_id 是两套东西，链接里带的是 num_iid。千万别把京东的 sku_id 当成淘宝的 num_iid 传进同一个字段，我在早期版本把两者混用，导致一整个类目的详情全查不到。

④ 短链展开

短链没有 ID，只能先跟重定向。这里有两个必须做对的地方：

第一，用手机 UA。 同一个 m.tb.cn 链接，桌面 UA 请求可能被重定向到一个带登录引导的中间页，Location 里没有商品 ID；手机 UA 通常会直接落到 item.taobao.com/item.htm?id=...。

第二，限制跳转次数并检查落点。 有的短链会先跳到活动落地页，再跳详情页，一次 HEAD 拿不到最终地址。

import requests

MOBILE_UA = ("Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) "
             "AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1")

def expand_short(url, max_hop=5):
    for _ in range(max_hop):
        r = requests.head(url, allow_redirects=False,
                          headers={"User-Agent": MOBILE_UA}, timeout=8)
        loc = r.headers.get("Location")
        if not loc:
            return url
        url = requests.compat.urljoin(url, loc)
        if re.search(r"item\.(taobao|jd)\.com|detail\.1688\.com", url):
            return url
    return url

短链展开的实测成功率并不高——3.cn 这类会有一定的跳转异常，所以我把展开失败的情况统一转入口令/链接转换接口。

⑤ 淘口令与链接转换

淘口令（¥xxxxxxxx¥）必须靠专用接口，正则解析不出来。淘宝平台的 item_password 后台统计成功率 95%，用来解口令是够用的；链接清洗与长短链互转用 item_link，它的成功率是 100%，是我这套链路里最稳的一环，我把它当"URL 归一化器"用——不管用户给的是淘客链、短链还是带一堆跟踪参数的长链，都先过一遍它。

def parse_password(text):
    url = "https://api-gw.onebound.cn/taobao/item_password"
    params = {
        "key": KEY, "secret": SECRET, "api_name": "item_password",
        "content": text,            # 直接传原始文案，接口自己找口令
        "result_type": "json",
    }
    r = requests.get(url, params=params, timeout=12).json()
    if r.get("code") != "0000":
        return None, r.get("code")
    return r.get("item", {}).get("num_iid"), "0000"

def normalize_link(link):
    url = "https://api-gw.onebound.cn/taobao/item_link"
    params = {"key": KEY, "secret": SECRET, "api_name": "item_link",
              "url": link, "result_type": "json"}
    return requests.get(url, params=params, timeout=12).json()

把口令和链接都归到 num_iid 之后，后面的详情、比价、加购链路就只需要面对一种入参。

三、四个花了两天才定位的坑

坑 1：& 被二次转义。 用户从浏览器复制来的链接里 & 可能已经是 &amp;，你直接塞进 params 字典，requests 会把它再编码一次，服务端拿到的 id 值就带上了尾巴。做法是解析前先做一次 html.unescape。

坑 2：淘口令有生命周期。 口令并不永久有效，过期后接口会返回业务失败。我给口令结果单独打了短 TTL（10 分钟）缓存，过期即失效，不做长缓存，避免用户拿到已失效的 ID。

坑 3：短链落到 landing page。 有些短链的落点是活动页，页面上有几十个商品链接。我的原则是只接受能唯一确定商品 ID 的落点，出现多个候选就判失败、转人工——选错商品的成本远高于多一次人工。

坑 4：cache 在这里要慎用。 解析类请求（item_link / item_password）我全部关掉缓存（cache=no），因为同一个短链在不同时间可能指向不同活动页；而详情接口（item_get）走缓存没问题。混用缓存策略是我早期最隐蔽的成本浪费来源。

四、落地成服务：缓存与指标

把上面的逻辑包成一个 POST /resolve 接口，入参是原始文本，出参是 {platform, goods_id, source}，source 标记它是从正则、短链还是口令拿到的。

关键是在缓存层做一层 raw_text → goods_id 的映射，因为同一段分享文案会被多个客服/多个用户反复粘贴：

def resolve(raw, ttl=7 * 24 * 3600):
    key = "rsv:" + hashlib.md5(raw.encode()).hexdigest()
    if cached := redis.get(key):
        return json.loads(cached)
    result = do_resolve(raw)                     # 五段链路
    if result["goods_id"]:
        redis.setex(key, ttl, json.dumps(result))
    return result

上线前后我记录了一组数据，解析失败率从 12.3% 降到 1.5%。下降主要由三块贡献：NFKC 归一化解决了一批全角/零宽字符导致的"看起来有链接、其实抽不出 ID"；item_link 接管了脏链接清洗；缓存把重复粘贴的解析请求从下游接口上摘掉了——命中率稳定在 60% 以上，也就是说超过一半的解析请求根本不到达网关层。

监控上我只看两个指标：按 source 分的解析成功率、未知平台的原始文本采样。后者尤其有用——unknown 占比突然上升，通常意味着某个平台改了分享文案模板，比等接口大面积报错要早发现半天。

解析完成后，拿到 num_iid / sku_id 就该走详情了。这里提醒一句选型：1688 的 item_get（99%）可以放心做主链路；淘宝的 item_get 后台统计只有 40%，必须配降级；京东详情用 item_get_pro（78%），并且 不要碰它的 item_search（28%）。选错入口，前面解析做得再漂亮也没用。

五、写在最后

这套链路的价值在于：把不确定性收在入口处，让下游永远只面对一种干净的入参。 解析这件事没有巧劲，就是把清洗、判定、抽取、兜底、缓存五段各自做扎实，然后盯着指标慢慢补边界。

接口参数我参考的是 open.onebound.cn/help/api，测试 key 我是在开放平台的控制台申请的，入口放这里，需要的自取：API 控制台

用图搜接口做反向海淘选品：从一张爆款主图到 12 条货源，全链路实战

Tue, 22 Sep 2026 11:38:49 +0800

反向海淘选品最难受的场景是：在海外社媒上刷到一个爆款，知道它长什么样，却不知道国内哪个供应商在做。靠关键词搜，翻译过去再搜回来，结果往往差得很远。这篇把我用图搜接口搭的选品链路完整写一遍——图片预处理、接口调用、结果去重排序、失败降级，附实测数据。

一、为什么关键词搜索在选品场景里不够用

先说我踩过的坑。早期我的选品流程是：看到爆款 → 人工描述品类词 → 翻译成中文 → 丢进搜索接口。

这条路有三个系统性误差：

品类词翻译误差。tote bag 翻成"托特包"，但供应商标题里写的是"大容量帆布单肩包"，词对不上，召回直接归零。
供应商命名不规范。同一个产品，标题里可能写"ins风收纳盒"“桌面杂物篮”“北欧简约置物筐”，没有稳定词根。
外观特征无法用文字表达。版型、花色、结构这些东西，文字描述天然是丢失信息的。

图搜正好补上第三点：它用视觉特征做召回，绕过了语言和命名的双重损耗。

二、接口形态与参数

请求走统一网关，图搜对应淘宝平台的 item_search_img：

GET https://api-gw.onebound.cn/taobao/item_search_img

公共参数三个平台一致：key、secret、api_name、cache、result_type、lang。图搜特有的业务参数：

参数	说明	实战取值
imgid	图片地址或 base64	公网可访问 URL，别用 localhost
page	页码	1 起步，选品场景 1~2 页足够
sort	排序	默认综合；找低价货源用价格升序
cache	是否走缓存	离线选品库用 yes，实时比价用 no
result_type	返回格式	json

为什么选它而不是别家：后台统计里，淘宝 item_search_img 的成功率是 92%，同一个平台的 item_search 是 85%。对比之下，1688 的 item_search 只有 53%，我从来不把它放在实时链路上。做图搜选品，入口选 92% 那个，不要为了"货源更全"去接 53% 的接口。

调用代码没什么花头：

import requests

KEY = "your_key"
SECRET = "your_secret"

def search_by_image(img_url, page=1, sort="price"):
    url = "https://api-gw.onebound.cn/taobao/item_search_img"
    params = {
        "key": KEY, "secret": SECRET, "api_name": "item_search_img",
        "imgid": img_url, "page": page, "sort": sort,
        "result_type": "json", "lang": "zh-CN",
    }
    r = requests.get(url, params=params, timeout=15).json()
    if r.get("code") != "0000":
        return None, r.get("code"), r.get("msg")
    return r.get("items", {}).get("item", []), "0000", ""

三、预处理这一步决定了 80% 的效果

**我把同一张原始主图直接丢进去，只回了 3 条结果，而且两条是无关品类。**把图做完预处理之后，同样一张图回了 12 条，前 5 条里有 4 条是同款。

预处理做四件事：

裁主体。社媒截图里通常有大量背景和文字浮层，主体占比可能不到 30%。先做主体检测裁剪，让商品占画面 70% 以上。
去水印和图注。浮层文字会被当成视觉特征参与匹配，直接污染结果。
压到 800px 长边、转 JPEG、质量 85。再大没有收益，只是白等网络。
统一白底。浅色商品配深色背景，容易召回一堆背景相似但品类不同的东西。

from PIL import Image, ImageOps
import io, oss_client   # 换成你用的对象存储

def preprocess(path, out_dir="tmp"):
    im = Image.open(path).convert("RGB")
    # 1. 主体裁剪：这里用你擅长的方式，检测框 + 10% 留白
    box = detect_subject(im)                 # 返回 (l, t, r, b)
    l, t, r, b = pad_box(box, im.size, ratio=0.10)
    im = im.crop((l, t, r, b))
    # 2. 统一白底
    im = ImageOps.pad(im, (im.width, im.height), color=(255, 255, 255))
    # 3. 尺寸与格式
    im.thumbnail((800, 800), Image.LANCZOS)
    buf = io.BytesIO(); im.save(buf, "JPEG", quality=85)
    return upload_to_cdn(buf.getvalue(), "goods.jpg")   # 必须返回公网 URL

这里有个容易忽略的点：imgid 必须是公网可访问的 URL。我一开始图省事直接传本地路径和 127.0.0.1 的地址，接口一律返回参数错误。要么先把图传到对象存储，要么传 base64（但 base64 会让请求体膨胀三四倍，批量选品时建议还是走 URL）。

四、结果去重与排序

图搜返回的是 items.item[]，每条字段大致是 num_iid、title、price、pic_url、detail_url、seller_info。选品场景要解决两件事：同一个货源被多个卖家重复铺货，以及价差巨大要挑出真实低价。

去重用感知哈希，不要用主图 URL 字符串比较——同一张图在不同店铺会被重新压缩、加边框：

def dhash(im, size=8):
    im = im.convert("L").resize((size + 1, size), Image.LANCZOS)
    px = list(im.getdata())
    bits = []
    for row in range(size):
        for col in range(size):
            bits.append(px[row * (size + 1) + col] > px[row * (size + 1) + col + 1])
    return int("".join("1" if b else "0" for b in bits), 2)

def dedup(items, threshold=6):
    kept = []
    for it in sorted(items, key=lambda x: float(x.get("price") or 0)):
        h = hash_of(it)                      # 缓存主图的 dhash，别每次重算
        if all(bin(h ^ k).count("1") > threshold for k in kept_hashes):
            kept.append(it)
    return kept

排序策略按业务目标走：做铺货选品按"销量 × 评分"排，做价格对标按价格升序 + 过滤掉明显异常的 0.01 元占位价。实测 12 条结果经过去重后剩 7 条独立货源，去重率大约四成——如果你不做这一步，选出来的"爆款"很可能全是同一家。

批量选品时把图片的 dhash 和结果一起落库，第二次遇到同一主图就能直接命中本地库，省掉一次调用。

五、失败降级与成本控制

图搜 92% 不低，但剩下 8% 你要有交代。我的降级链是：图搜 → 关键词搜索（item_search，85%） → 入人工待处理队列。

def pick_by_image(img_url, fallback_kw=None):
    items, code, msg = search_by_image(img_url)
    if items:
        return {"source": "img", "items": dedup(items)}
    if fallback_kw:
        kw_items, code2, _ = search_by_keyword(fallback_kw)
        if kw_items:
            return {"source": "kw", "items": dedup(kw_items)}
    return {"source": "manual", "items": []}

两个成本细节值得记住：

错误码决定钱。0000（成功）和 2000（搜索成功但没有结果）都会计费；4000 / 4001 / 4002 / 4017 这类鉴权、参数、服务端与网络异常不计费。所以参数校验要在本地做干净，别把本地拼错的 URL 发出去——那虽然不计费，但浪费时间配额。
cache 用对地方。选品库是典型的离线场景，同一张图短期内反复搜没有意义，一律 cache=yes。只有在做实时比价、需要最新价格时才传 cache=no。我的选品库任务全量打开缓存后，同一批图片的重复调用成本基本被吃平了。

最后一个经验：图搜返回的是平台在售商品，不是供应商。看到合适的结果后，还要再走一次详情接口拿 sku 和起订量，才能判断能不能代采。这一步我用 1688 的 item_get（后台统计 99%），稳定得几乎不用兜底。

六、写在最后

图搜选品的核心链路其实是四段：把图洗干净 → 用可靠性高的入口搜 → 去重再排序 → 给失败留退路。真正拉开效果差距的是第一段和第三段，接口本身反而最简单。

测试 key 我是在开放平台的控制台申请的，入口放这里，需要的自取： API 控制台

1688 代采系统实战：SKU 阶梯价、快递费和搜索降级这三个坑，我踩了两个月

Mon, 21 Sep 2026 11:05:39 +0800

代采系统的难点不在"拿到商品详情"，而在"下单前那一刻能不能算对钱"。这篇是一次完整的排障记录：SKU 阶梯价怎么选、运费怎么估、找货搜索接口只有 53% 成功率怎么办。全部是实测数据和可直接复用的代码，写给正在做代采、铺货、反向海淘报价的朋友。

一、先明确一件事：代采系统的技术核心是"报价"

代采的业务闭环是：客户给链接 → 系统给出到手价 → 客户付款 → 系统去 1688 下单。中间最脆弱的一环是报价，而报价依赖三个数据：SKU 单价、数量对应价格、运费。任何一个算错，要么自己亏钱，要么客户跑单。

我把 1688 这条线（走 https://api-gw.onebound.cn/1688/{接口名}）跑了两个月，后台统计的成功率是这样：item_get、item_get_app、item_get_pro、custom 都是 99%，cat_get 97%，item_fee 96%，但 item_search 只有 53%。这组数字直接决定了下面三个坑怎么填。

二、坑一：SKU 阶梯价，直接用 price 字段一定出事

1688 的商品大量是批发价，价格不是一个数字，而是一段区间。item_get 返回的 skus.sku[] 里，每个 SKU 都可能有 price、quantity（起订量）和 price_range（阶梯区间）。我最初只取 price，结果客户订 1000 件时系统按 1 件的价格报出去，单笔亏了几百块。

正确做法是按采购量匹配阶梯：

def pick_price(sku, qty):
    # sku["price_range"] 形如 "1-99:3.20;100-499:2.85;500-:2.40"
    ranges = []
    for seg in (sku.get("price_range") or "").split(";"):
        if ":" not in seg:
            continue
        span, price = seg.split(":")
        lo, _, hi = span.partition("-")
        ranges.append((int(lo), int(hi) if hi else 10**9, float(price)))
    for lo, hi, price in sorted(ranges):
        if lo <= qty <= hi:
            return price
    return float(sku.get("price", 0))

配套有三个细节：一是 is_promotion=1 时拿到的是促销价，报价口径必须和前端展示口径一致，否则客户看到的和下单价对不上；二是 quantity 是最小起订量，低于它要么拒单要么走一件代发通道；三是 SKU 的 properties_name（如"颜色:黑色;尺码:XL"）要完整透传给下单侧，否则人工下单时对不上规格。

另外提醒一句：主链路的 99% 成功率意味着这层几乎不用写重试，但类目字段的差异要提前处理，不同类目下 skus 可能是数组、可能是空对象，解析前先判类型。

三、坑二：运费预估，item_fee 不是你以为的那样

代采报价必须含运费，我用的是 item_fee（实测 96%）。它的入参除了 num_iid，关键是收货地区 ID，而地区 ID 来自 cat_get 那一类的行政区划数据，需要提前离线同步一份本地映射表——在线实时查行政区划既慢又浪费调用量。

r = call("1688", "item_fee", num_iid="674532958902", area_id="360700")
fee = r["item"]["express_fee"]      # 单位：元

两个实操经验：第一，item_fee 返回的是快递报价，对重量敏感的大件（家具、大件家电）偏差明显，我在报价侧加了一个体积重校验，超过阈值直接提示"运费面议"，比硬报一个错价安全；第二，发货地会影响运费，代采下单前拿到的发货地要重新校验一次，跨省调货的场景我遇到过一次报价和实付差 30 块。

四、坑三：搜索只有 53%，别拿它做主链路

这是最花时间的一个坑。代采系统有个"客户不知道要买哪家，输入关键词找货"的功能，我一开始直接接了 item_search，结果近一半的搜索请求返回失败或空结果，客服每天被问"为什么搜不出来"。53% 的成功率做实时搜索，产品体验是不可能成立的。

我最后改成三层组合，绕开了对搜索的强依赖：

本地商品池：客户历史询价过的商品全部入库，搜索优先走自己的 ES，命中率覆盖了七成以上的重复询价；
类目树下钻：用 cat_get（97%）把类目树离线落库，客户可以从"类目 → 子类目 → 商品"逐级进入，这条路径不依赖搜索接口；
关键词搜索兜底：只有前两条都没命中时才调 item_search，且失败时前端展示"暂未找到，可粘贴链接直接报价"，把失败转成引导动作。

改造之后，搜索模块的有效响应率从 53% 提到 96% 以上，调用量反而下降了——因为本地池消化了大部分请求，成本也降了。

五、顺带说下错误码里的成本规则

0000（成功）与 2000（搜索成功但无结果）计费，4000 / 4001 / 4002 / 4017 这些服务端错误、网络错误、超时都不计费。所以搜索返回 2000（没搜到东西）是要花钱的，上面那套"本地池优先"的策略不只是为了体验，也是在省钱。超时设置同样建议给到 10 秒以上，避免客户端主动断开导致"服务端已计费、本地没数据"的双输。

六、写在最后

三个坑的共同点是：接口本身很稳，坑都出在"怎么用"。把 SKU 价格口径、运费口径、失败路径定清楚，代采系统的报价准确率能做到接近 100%。接口参数我是对着 open.onebound.cn/help/api 逐个核的，测试 key 是在万邦开放平台的控制台申请的，入口放这里，需要的自取：API 控制台

反向海淘独立站的数据层架构：1688 / 淘宝 / 京东三平台接口怎么编排与降级

Mon, 21 Sep 2026 11:01:25 +0800

做反向海淘独立站，前端、支付、物流其实都有成熟方案，真正容易把项目拖死的是数据层——商品从哪来、怎么归一化、接口挂了怎么办。这篇把我现在跑的这套三平台数据层架构完整拆开，包括分层设计、降级链、缓存策略和成本控制，给正在搭系统的朋友一个可以直接抄的骨架。

一、为什么数据层是最先崩的地方

反向海淘的商品来源天然是分散的：1688 拿货、淘宝找同款、京东做价格对标。三个平台三套字段、三套反爬、三套失败率。很多团队一开始的做法是"哪里需要就在哪里写一次请求"，结果三个月后代码里躺着几十处硬编码 URL，某个接口一抖动，全站跟着白屏。

问题的根子是把"取数"和"用数"耦合在了一起。正确的做法是先分层。

二、三层结构：采集层 / 归一化层 / 业务层

采集层只做一件事：给定平台和参数，返回原始 JSON。所有请求都走同一个网关形态 https://api-gw.onebound.cn/{平台}/{接口名}，公共参数固定为 key、secret、api_name、cache、result_type、lang。用一个适配器字典管理平台差异：

GATEWAY = "https://api-gw.onebound.cn/{platform}/{api}"

PLATFORM_API = {
    "1688":  "item_get",       # 详情主链路
    "taobao": "item_get",
    "jd":    "item_get_pro",
}

def call(platform, api, **params):
    url = GATEWAY.format(platform=platform, api=api)
    base = {"key": KEY, "secret": SECRET, "result_type": "json"}
    return requests.get(url, params={**base, **params}, timeout=12).json()

归一化层负责把三个平台返回的商品对象，映射成同一种内部模型（SPU + SKU 列表 + 价格区间 + 主图数组）。这层写死了字段映射表，业务层就永远只面对一种数据结构。淘宝的 num_iid、1688 的 num_iid、京东的 sku_id 在归一化层统一成 platform_goods_id，后面换接口、加平台都不用动业务代码。

业务层才是定价（汇率 × 加价率 × 物流系数）、库存同步、上下架这些真正属于你产品的东西。

归一化层的映射表建议显式写死，不要靠猜测字段名：

内部字段	1688	淘宝	京东
platform_goods_id	num_iid	num_iid	sku_id
title	title	title	title
price	price / price_range	price	price
images	pic_url + item_imgs	pic_url + item_imgs	pic_url
skus	skus.sku[]	skus.sku[]	skus.sku[]
seller	seller_info	seller_info	shop_info

这张表是三个月里改动最频繁的文件，但它的价值在于：任何平台的接口变动，都只影响这一张表，业务层完全无感。顺带说一句，京东没有独立的"阶梯价"概念，price 单值即可，而 1688 必须处理区间价——这个差异放在归一化层消化，比散落在报价逻辑里安全得多。

三、降级链：按实测成功率排兵布阵

架构里最有价值的是降级链。我把后台统计的成功率数据（样本量十万次级）做成了一张"可靠性分层表"，接口按可靠性分三档用：

平台	接口	成功率	定位
1688	item_get / item_get_app / item_get_pro / custom	99%	主链路，几乎不需兜底
1688	cat_get	97%	类目树，离线同步
1688	item_fee	96%	运费预估
1688	item_search	53%	⚠️ 不做实时主链路
淘宝	item_link	100%	链接转换，最稳
淘宝	item_search_shop_pro	96%	店铺采集
淘宝	item_password	95%	淘口令解析
淘宝	item_search_img	92%	图搜选品
淘宝	item_search	85%	搜索，可用
淘宝	item_get / item_get_pro	40%	⚠️ 必须做降级
京东	cat_get	100%	静态数据
京东	item_review	99%	评论
京东	item_get_desc	98%	描述
京东	item_get_pro / item_get	78%	可重试使用
京东	item_history_price	75%	比价够用
京东	item_search	28%	⚠️ 避开主链路

看这张表的结论很明确：1688 的详情链路可以放心当主链路用，淘宝和京东的详情接口必须配降级。淘宝 item_get 只有 40%，意味着每一次"用户粘贴链接"的请求都有六成概率失败，如果直接同步返回给用户，体验会直接崩掉。我的做法是给它挂一条降级链：

DEGRADE = {
    ("taobao", "item_get"): ["item_get_pro", "item_search_shop_pro", "custom"],
    ("jd",     "item_get_pro"): ["item_get", "item_get_desc"],
    ("1688",   "item_get"): [],          # 99%，不配降级，省一次调用
}

def fetch_with_fallback(platform, api, **params):
    for candidate in [api] + DEGRADE.get((platform, api), []):
        for attempt in range(2):          # 每个接口重试一次
            r = call(platform, candidate, **params)
            if r.get("code") == "0000":
                return candidate, r["item"]
        time.sleep(0.3)
    return None, None                     # 交给上层入待补采队列

注意最后那行 return None, None 不是失败，而是转入异步补采队列。前端立刻返回"数据同步中"，后台任务稍后补齐。这一层设计让我的实时接口成功率从 40% 的体感，变成了用户侧 100% 的可响应率。

四、缓存与成本：两个容易漏的细节

第一，cache 参数默认走缓存，铺货、建库这类离线场景一定要用缓存，速度快、成本低；只有实时比价才显式传 cache=no。

第二，错误码直接决定钱。0000（成功）和 2000（搜索成功但无结果）计费，4000 / 4001 / 4002 / 4017 这类服务端与网络错误不计费。所以客户端超时不要设太短——超时主动断开时服务端可能已完成调用，白付一次还拿不到数据。我给到 12 秒，配合重试，长期看反而更省。

第三个容易被忽略的是监控。我在采集层出口统一打了三个指标：按"平台 + 接口"维度的成功率、P95 耗时、以及失败错误码的分布。当某个接口的成功率连续 30 分钟低于它历史基线（比如淘宝 item_get 从 40% 掉到 20%）时自动告警，此时应该立刻把它从降级链首位摘掉，而不是等用户投诉。这套指标另一个用途是对账：每月把各接口的计费调用量按错误码分组统计一次，和账户扣减额度对齐，能提前发现调用量异常增长的模块。

五、写在最后

数据层架构的核心就一句话：把接口的不确定性，关在适配器里。上层业务永远假设数据会来，只是可能晚一点来。测试 key 我是在控制台申请的，入口放这里，需要的自取：API 控制台

做比价系统半年，我把京东商品数据接口的坑都踩了一遍

Sun, 20 Sep 2026 15:29:06 +0800

去年立项做了一个京东商品的比价监控工具，从选数据接口到上线跑了半年。这篇不聊产品，只聊技术选型里的实际数据：哪些接口稳、哪些接口别碰、错误码里藏着的省钱规则。给要做价格监控、评论分析、选品工具的朋友避避坑。

一、先说结论：京东系接口怎么选

京东的数据获取难度和淘宝系不一样——页面结构相对规整，但反爬对高频请求非常敏感。自己维护爬虫在低频场景能跑，一旦做"分钟级价格监控"就很难扛住。所以比价系统这种 7×24 跑的，我还是选了第三方接口网关的方案。

接了半年，后台统计的实际成功率数据（样本十几万次调用）如下，我做了一张选型参考表：

接口	用途	成功率	我的评价
item_get_pro	详情高级版	78%	主力接口，可用
item_get	商品详情	78%	备选
item_get_desc	商品描述	98%	非常稳，放心用
item_review	商品评论	99%	最稳的一个
cat_get	分类数据	100%	静态数据，基本不失手
item_history_price	历史价格	75%	比价核心，够用
item_search	关键词搜索	28%	⚠️ 别做主链路
item_search_pro	高级搜索	0%	实测期间全挂
item_get_app	移动端详情	0%	实测期间全挂

选型建议一句话版：详情和评论走 item_get_pro / item_review，描述和类目随便用，搜索需求绕开或者做缓存降级。

二、比价系统的架构里，接口怎么排兵布阵

我实际的分工是这样的：

价格监控主循环：定时任务对监控列表里的商品调 item_get_pro，取促销价和时间戳入库。78% 的成功率听起来不高，但配合"失败重试一次 + 下一轮补采"的策略，实际数据完整率能做到 95% 以上，因为比价场景对实时性要求是分钟级，不是秒级。
商品入库时的内容同步：标题、详情描述走 item_get_desc（98%），这部分基本零维护。
评论分析模块：差评关键词聚类是比价工具的一个卖点，item_review 99% 的成功率让这个模块完全无人值守。
搜索发现模块：用户输入关键词找商品，这个我是用搜索词联想 + 自己维护的热榜池来降低对 item_search 的直接依赖，因为它只有 28% 的成功率，直接上主链路会被用户骂。

三、错误码里的省钱规则，很多人不知道

接入前一定要把错误码表看熟，因为不同错误码的计费策略不一样：

0000 调用成功 —— 计费
2000 搜索成功但无结果 —— 计费
4000 / 4001 / 4002 / 4017（服务端错误、网络错误、超时）—— 不收费
4003~4016（参数错误、账户问题等）—— 不计费，忽略

两个实操建议：

超时别急着判失败。4002 超时不收费，但如果你在客户端设了 3 秒超时主动断开，服务端可能已经完成调用并计费了。超时时间给到 10 秒以上，既省钱又稳定。
对账脚本按错误码分组统计。我每月跑一次对账，把"应计费调用量"和"账户扣减额度"对齐，半年下来没错过一笔。

四、一个真实的坑：促销价和历史价对不上

上线第二周收到用户反馈：价格曲线显示昨天降价了，但点进去价格没变。排查后发现是 is_promotion 参数的问题——历史价格接口取的是促销价，实时详情我默认没传促销标志，两边口径不一致。

解法：全链路统一用 is_promotion=1，同时把"到手价 vs 划线价"两个字段分开存，前端明确标注口径。这个坑让我们的价格曲线可信度提升了一大截。

五、工具与入口

我在用的接口网关是万邦开放平台，京东、淘宝、1688 都在一个后台里管，测试 key 直接在控制台就能申请：API 控制台

下一篇打算写"淘宝系接口的选型"，那里面的门道更多（图搜、淘口令、店铺采集各有各的脾气），感兴趣的关注一下。

万邦api博客

反向海淘代购系统开发实录：从业务链路到可运行代码

一、先定义问题：反向海淘代购系统到底在解决什么

二、全链路业务流程

三、技术架构分层

四、六大核心模块拆解

4.1 商品同步：为什么"全量爬"这条路走不通

4.2 多币种报价引擎

4.3 集运合单：整个系统最能省钱、也最容易被投诉的模块

4.4 订单状态机

4.5 多语言与内容本地化

4.6 支付与对账

五、8 条血泪踩坑清单

六、技术选型建议

七、这套系统适合谁

八、快速落地：不必从零造轮子

九、小结

闲鱼商品列表API接口商品详情API接口请求示例（含一份真实响应数据示例）

京东 item_get_pro 返回的 5 个价格字段到底用哪个？一份真实数据讲清楚

一、先想清楚：你到底需要拿商品详情的哪一部分？

二、接口概览

三、返回数据的整体结构

四、核心字段逐个拆解

① 基础标识

② 价格体系（⚠️ 最容易踩坑的地方）

③ 库存与销量

④ 品牌与类目

⑤ 图片与视频

⑥ 规格属性

⑦ SKU 列表（整个接口最有价值的部分）

⑧ 卖家与店铺

⑨ 响应元信息

五、Python 实战：3 分钟跑通并解析出价格区间 + SKU 表格

Step 1 · 请求封装

Step 2 · 图片链接补全（必做）

Step 3 · 解析 SKU，输出价格区间

Step 4 · 直接转成表格（铺货/运营最爱）

Step 5 · 顺手生成商品参数表

六、8 个实战踩坑点（都是真金白银换来的）

七、典型落地场景

八、接口获取与成本

九、小结

找热销爆品工具之api系列：1688图片搜索商品item_search_img

一、为什么需要「以图搜货」？

二、接口能力速览

三、接入前准备：图片规范决定成败

3.1 图片硬性规范

3.2 传图二选一

3.3 图片预处理建议（提升匹配率的关键）

四、核心参数详解

4.1 公共参数（必填）

4.2 业务参数

五、签名生成原理

六、Python 完整实战

6.1 安装依赖

6.2 核心代码

6.3 结果示例（控制台）

6.4 联动「商品详情接口」补全采购字段

七、返回字段全解析

7.1 顶层结构

7.2 单个商品字段（item[]）

八、五大落地场景

场景 1：跨境选品 / 无货源铺货

场景 2：企业采购寻源 / 样品比价

场景 3：商品溯源 / 侵权排查

场景 4：ERP / 供应链 SaaS 集成

场景 5：批量图库匹配

九、性能优化与踩坑排错

9.1 常见报错与原因

9.2 优化建议

十、合规提示

十一、总结

1688 / 京东 / 淘宝 item_get 返回字段逐个拆：三个平台的真实报文差在哪

一、请求侧：一个网关跑三个平台

二、1688：item 里最需要看清的字段

三、京东：字段名相似，能力边界差很多

四、淘宝：字段最全，但 item_get 的成功率是硬伤

五、字段映射表：让三个报文落进同一张表

六、收尾

反向海淘系统最脏的输入：把用户粘贴的分享文案、淘口令、短链统一解析成商品 ID

7.2 单个商品字段（`item[]`）

二、1688：`item` 里最需要看清的字段

四、淘宝：字段最全，但 `item_get` 的成功率是硬伤