接口是一个地址加一个动作名,以及一个会让你误判成功的返回约定

这一页写给两种人:要把这边的库存接进自己系统的,和在评估要不要接的。不谈架构形容词,只说接上去之后你会看到什么。

形态:一个地址,动作写在请求体里

不是一堆按资源分的地址,而是一个地址收所有请求,要做什么用请求体里的动作字段说明,密钥也放在请求体里,不走请求头。这是面板类系统多年来的通行做法,好处是现成的对接代码基本能直接用,坏处是它和多数人熟悉的现代接口写法不一样,第一次看会觉得别扭。

标准的六个动作都在:取服务列表、下单、查订单状态、查余额、补量、取消。这六个是面板生态里被广泛实现的那一组,按它们写的对接代码可以直接连过来。

在这之上还有一些不属于那套约定的扩展,用来处理这边特有的东西:分类和子分类信息、商品、店铺、库存,以及短信验证相关的一组动作。这些是这边独有的,别的面板上没有,所以现成的代码不会用到它们,要用得自己加。

所以「不用改任何代码就能接过来」这句话要打个折:按标准六个动作写的部分是这样,用到别的东西的部分不是。

出错的时候返回码还是 200

这一条单独拿出来说,因为它最容易造成误判。

密钥无效、账号未通过审核、超出频率限制,这些情况下接口返回的仍然是正常的返回码,错误信息在返回体的字段里。也就是说,如果你的代码是先看返回码再决定要不要解析内容,那么一个密钥填错的请求在你的日志里会被记成成功,而实际上什么都没发生。

正确的判断方式只有一种:每次都解析返回体,先看里面有没有错误字段,有就当失败处理。这一点在你写第一行对接代码之前就要定下来,后面再改要翻遍所有调用点。

频率限制在取服务列表那一个动作上

取服务列表这个动作有单独的频率限制,同一个密钥两次调用之间有一个最小间隔,默认是两秒。超了不会报错崩掉,会返回一个带着还要等多久的提示,单位是毫秒,照着等就行。

实践上这意味着一件事:不要把取列表放在循环里当轮询用。正确做法是定时拉一次全量、在自己这边缓存,下单和查状态那些动作不受这个限制。

密钥认的是账号,不分买卖双方

认证只看密钥本身,不检查你是买家还是卖家,也不检查订阅状态。所以同一套接口既能用来接自己的采购流程,也能用来接自己的供货流程,不需要两套凭据。

有一个前置条件要注意:如果站点当前开着供应商需要审核这个开关,而你的卖家账号还没通过,接口会明确返回待审核,这时候不是密钥的问题,是账号状态的问题。

另外还有一套面向管理端的接口挂在另一个地址上,那是给需要更深整合的场景用的,和上面这一套是分开的两条线。

目前接进来能看到多少东西

截至今天:553 家在营店铺,16,874 条已上架的在售商品,30,600 条在售的增长服务。已经建了密钥的账号有 293 个。

这几个数字里,和对接决策最相关的是最后一个:三百个不到,说明接口是能用的但还不是主流用法,遇到边角情况时可参考的先例不多,所以第一次接的时候把日志开细一点比较划算。

和自动发卡系统不是一回事

中文里搜「自动发卡」的人不少,但那个词指的是你自己搭一套卡密售卖系统,货源、结算、售后都归你。这边是另一种东西:多家独立卖家在同一个目录里挂单,付款到放款之间隔着一段时间,出问题走站内的纠纷流程。这里要把话说准,别沿用「等买家确认」那个说法:站内 89,467 笔已完成订单里有 74,925 笔、也就是 83.7%,是计时器自动确认的,不是买家点的。真正会挡住放款的是这张订单上开着的工单。

判断自己要哪一种,一句话就够:你手里已经有稳定货源、只缺一个卖货的前台,那你要的是自建系统;你要的是货本身,或者要的是有第三方兜着的成交流程,那才是这边。两类的完整对比在这一篇里。

要动手的话,卖家侧的商品管理和手动订单接口各有单独的说明文档,分别在商品管理指南和手动订单接口指南里,建议先用后台把整个流程手动跑通一遍,再把已经跑通的那部分自动化。