ERP对接在 ManoMano 这件事上,要拆成两条线看:一条是订单与发货状态的读写,一条是包裹在路上的轨迹明细。前一条平台给得痛快,后一条平台基本不管,数据由承运商产生。把两条线混成一件事做,上线后最典型的现象是后台点了发货、买家页面查不到任何节点。这篇讲清轨迹从哪来、接口怎么开、四段同步各自的时点,以及最常断的三个地方。

物流轨迹,ERP对接,同步逻辑

一、轨迹的源头在承运商那一段

平台自己不做轨迹采集。卖家接口拿到的是订单对象、履约状态、退货与结算,包裹经过哪个分拣中心、几点完成派送,这些字段不在平台手里。平台做的是把卖家回传的运单号与承运商编码对上,再去承运商的查询通道取节点,取不到就在页面上留一段空白。

所以要接的是两个外部对象,不是一个。一边是平台的订单与发货接口,负责告诉平台这单发了、单号是什么、承运商是哪家;另一边是承运商的查询接口,或者一家能覆盖多承运商的聚合服务,负责把节点拉回来。两边都通,买家才看得到完整链路。

承运商编码是最容易吃亏的字段。填三个字母的缩写,平台不知道要走包裹网还是快递网;填了大网而实际走的是同一集团的小件产品线,节点对不上还会被判轨迹异常。这类错误在后台看不出问题,只有买家投诉时才暴露。

二、开接口先过权限这一关

接口权限走授权协议,入口在卖家账号的设置里。卖家申请一组客户端凭据,把凭据交给系统,由系统换取访问令牌。权限按范围勾选,只勾了订单读取没勾发货写入,系统能拿到订单但回不了状态,表现是订单一直停在待发货,看着像接口坏了。

令牌有有效期,刷新机制必须实现。不少自研对接上线时能用,跑几天突然全体失败,原因就是到期没换新令牌。工程上要做的事很简单:到期前主动刷新,刷新失败要能报警,别等订单堆起来才有人发现。

多站点要注意归属。同一家卖家在不同国家站点各有一个身份,订单号与商品编号在不同站点可能是两套。用一套凭据去查另一个站点,返回的是空列表而不是报错,排查时很容易被误导成没有新订单。

凭据的保管要有规矩。密钥写在代码里、推到公共仓库、离职人员手上还留着,都等于把账号交出去。生产与测试分开两套,切换时改配置不改代码。

三、四段同步各自的时点

订单进来是第一段。系统按固定间隔拉新订单,间隔太长会把发货时点往后压,太短会触发限流。多数平台对拉取频率有软上限,超过之后返回延迟而不是拒绝,看起来像网络慢,其实是自己在挤自己。

发货回传是第二段,也是最关键的一段。回传要带三样东西:运单号、承运商编码、发货时间。少了承运商编码,平台只能靠单号猜,猜错就查不到节点;发货时间填本地时间还是站点时区,也要跟平台口径对齐。

轨迹拉取是第三段。包裹刚交付承运商时可能几小时才有第一条扫描,拉得太勤只是重复请求。合理做法是按发货后的小时数分档,前期密后期疏,超过一定天数还没签收就转人工,不再靠轮询硬等。

轨迹回写是第四段。有些平台允许把节点写进订单的物流字段,有些不接受外部写入。能不能写要看接口文档里有没有对应方法,硬写会返回参数错误,日志里只留一条失败记录,很容易被忽略。

四、断点集中在三处

断在单号上的情况最常见。系统里的单号带空格、带横线、带前缀,平台校验时判为格式不合法,整条回传失败。批量导入会一次性暴露一大批,单条手工发货时往往没人注意,等到时效考核扣分才发现。

断在商品编码上的也不少。一边传的是带分隔符的编码,另一边备案的是去掉分隔符的同一串,两边对不上,系统认为商品不存在,发货动作直接被拦。上线前把编码规则写进映射表,比事后逐条改省事得多。

断在承运商名单上的最隐蔽。平台只认自己名单里的承运商,走名单外的渠道,即便单号真实有效也传不上去。换渠道之前先查名单,换完再刷一遍历史订单,看有没有积压的失败记录。

还有一种断法是时间戳错位。服务器时区与站点时区差几个小时,回传的发货时间落在订单创建之前,平台判为逻辑错误。这类问题只在跨时区的站点出现,单站点测试永远测不出来。

排查要有顺序。先看请求有没有发出去,再看对方返回的状态码,再看返回体里的错误字段。跳过前两步直接改数据,改的往往是没问题的部分。日志要留全量请求体,只留状态码等于没留。

五、上线前跑一遍验证

验证要从一张真单开始。下一单走完整链路:订单抓取、发货回传、承运商首扫、节点回写,每一步记下时间戳,链路总耗时就出来了。用假单号测只能验证接口通不通,验证不了轨迹。

验证还要覆盖失败路径。故意填错承运商编码,看系统是报错还是静默失败;故意让令牌过期,看告警有没有触发。失败路径不测,上线后第一次出事就是全线停摆,那时再补监控已经晚了。

日常动作只有三件:每天看一次失败队列、每周对一次承运商名单、每次换渠道前重跑验证单。这三件事花不了多少时间,但能把轨迹缺失压在很低的水平。对接从来不是一次性工程,是需要定期维护的链路。