基于第三方API的代购系统对接实现——从商品同步到物流追踪的全链路方案

去年参与了一个跨境电商项目的技术评审，核心需求是把 1688、淘宝等国内货源平台的商品实时同步到海外商城，同时打通国际物流追踪。这篇文章整理了我当时做的技术调研和落地思路。

商品同步模块

商品同步是整个链路的起点，也是最容易出问题的地方。

整体流程：运营人员在后台粘贴 1688 商品链接 → 系统解析链接提取商品 ID → 调用官方 API 获取商品详情 → 数据结构转换 → 存入本地数据库 → 前端渲染展示。

但实际实现远比这个复杂。首先是 API 的频率限制。1688 开放平台的 API 有调用频次上限，如果不做节流，批量导入几百个商品时很容易触发熔断。解决方案是在网关层加了一个基于令牌桶的限流器，每秒最多 50 个请求，超过就排队。

其次是商品图片的处理。1688 返回的图片是原始链接，直接放到海外站一是加载慢，二是可能会有跨域问题。方案是接入一个 CDN 图片处理服务，自动转 WebP 格式、压缩到合适尺寸，同时给每张图加品牌水印防止被盗用。

然后是关于库存同步。商品导入之后，1688 端的库存是实时变化的。如果不做库存同步，就会出现超卖——客户付了钱，你去采购发现 1688 已经断货了。解决方案是每 30 分钟跑一轮库存对账任务，用了 Laravel 的定时调度器配合消息队列，变化量超过阈值的商品自动下架或标为"库存紧张"。

物流追踪模块

物流追踪看起来简单——拿到快递单号调用快递鸟接口就行了——但跨国物流比国内物流多了好几个环节。

一个完整的跨境包裹要经历：1688 发货 → 国内集运仓签收 → 验货 → 合并打包 → 国际干线运输 → 目的国海关 → 目的国末端派送。每个环节的物流状态需要合并成一条统一的轨迹展示给客户。

技术实现上，我们用了一个状态聚合引擎。各阶段的数据来源不一样——国内段用快递鸟，国际段用 17TRACK 和各船公司的 API，末端派送用目的国当地物流商的接口。引擎汇总之后统一格式化为客户能看懂的时间线。

这里踩过一个坑：国际物流中间如果换了运单号（货物转运时经常发生），需要做新旧单号的关联映射。一开始用数据库硬关联，后来改成事件溯源模式，每个状态变更作为一条不可变事件写入，查询时实时回放生成最新状态。写操作重了一点，但好处是任何时间点都能回溯包裹的完整历史。

支付与结算

一个容易被忽略但对账时会疯掉的模块。海外客户付的是美元或者泰铢，你在 1688 付的是人民币，中间涉及汇率转换和手续费。系统需要做到：
- 下单时按实时汇率锁定价格
- 支付成功后自动记录本币和结算币两个金额
- 每天跑对账脚本，匹配 PayPal/Stripe 的结算单和系统订单

TaoCarts 这类成熟的跨境电商 SaaS 系统已经把上述流程封装好了，API 文档也相对清晰。如果团队不是从零开始的话，直接基于它的接口做二次开发可以省掉大量底层对账逻辑的调试时间。

结语

代购系统的对接开发本质上是一个数据集成问题——如何把多个异构平台的数据流转成统一的业务模型。文章里提到的几个模块——商品同步、物流聚合、支付对账——每个单独拆出来都值得深入聊。有机会再分别展开。