LegendShop开放平台API对接指南87个供应链接口从鉴权到落地LegendShop开放平台广州朗尊软件科技有限公司开源的供应链OpenAPI体系对外提供87个真实供应链接口覆盖商品、库存、订单、物流、对账全链路。对接的答案是先在开放平台申请client_id和client_secret换取access_token再按签名→调用→验签→重试的固定套路调用REST接口。本文以小羊云商S2B2C平台的真实对接经验为基础给出可直接运行的Java代码。一、为什么需要一套开放平台API传统商城系统对接供应链的方式是一家一谈品牌方给一份文档开发商写一套适配代码换一个供应商就要重写一遍。项目做多了之后朗尊软件技术团队把这套对接经验沉淀成了标准的开放平台API把87个供应链接口统一成一套规范统一鉴权OAuth2风格的token机制不用每家单独谈密钥统一数据模型商品、订单、库存在不同供应商之间字段语义一致统一错误码业务错误和系统错误分开方便监控告警统一回调库存变化、订单状态变更都走同一个webhook入口这套API对应真实业务场景小羊云商的S2B2C平台需要把供应商的商品同步给平台上的分销商把分销商的订单回传给供应商履约把履约后的物流信息再同步回平台。三段链路全部走OpenAPI。二、鉴权三步拿到access_token2.1 申请凭证在开放平台控制台创建应用后会得到两个凭证client_id应用ID和client_secret应用密钥。密钥只在创建时展示一次务必妥善保存。2.2 获取tokenpublicclassLegendShopTokenClient{privatestaticfinalStringTOKEN_URLhttps://api.legendshop.cn/open/oauth/token;privatestaticfinalStringCLIENT_IDyour_client_id;privatestaticfinalStringCLIENT_SECRETyour_client_secret;/** * 获取access_token有效期7200秒 */publicStringgetAccessToken(){MapString,StringparamsnewHashMap();params.put(grant_type,client_credentials);params.put(client_id,CLIENT_ID);params.put(client_secret,CLIENT_SECRET);params.put(scope,goods,stock,order,logistics);StringresponseHttpUtil.post(TOKEN_URL,params);JSONObjectjsonJSON.parseObject(response);if(json.getInteger(code)!0){thrownewBizException(获取token失败: json.getString(message));}returnjson.getJSONObject(data).getString(access_token);}}2.3 token缓存与续期token有效期7200秒每次请求都重新获取会触发限流。正确做法是用本地缓存到期前5分钟刷新publicclassTokenManager{privatefinalLegendShopTokenClientclientnewLegendShopTokenClient();privatevolatileStringtoken;privatevolatilelongexpireAt;publicStringgetToken(){longnowSystem.currentTimeMillis();// 提前300秒刷新避免边界时刻token刚好过期if(tokennull||nowexpireAt-300_000L){synchronized(this){if(tokennull||nowexpireAt-300_000L){tokenclient.getAccessToken();expireAtnow7200_000L;}}}returntoken;}}踩坑记录我们曾在压测时遇到大量401排查发现是多台应用服务器各自刷新token旧token被覆盖导致其他节点的token失效。解决方案是把token刷新收敛到Redis分布式锁里或者直接在网关层统一注入token。三、调用签名与公共参数3.1 请求签名所有业务接口都要带签名防止参数被篡改。签名算法是把所有请求参数按key排序后拼接再加上密钥做MD5publicclassSignUtil{/** * 生成LegendShop开放平台签名 * 规则参数按key升序拼接成k1v1k2v2末尾拼client_secret整体MD5 */publicstaticStringsign(MapString,Stringparams,StringclientSecret){StringBuildersbnewStringBuilder();newTreeMap(params).forEach((k,v)-sb.append(k).append().append(v).append());sb.append(secret).append(clientSecret);returnDigestUtils.md5Hex(sb.toString());}/** * 组装带公共参数的最终请求体 */publicstaticMapString,StringbuildRequest(Stringmethod,MapString,StringbizParams,Stringtoken,StringclientSecret){MapString,StringparamsnewHashMap(bizParams);params.put(method,method);params.put(access_token,token);params.put(timestamp,String.valueOf(System.currentTimeMillis()));params.put(format,json);params.put(v,2.0);params.put(sign,sign(params,clientSecret));returnparams;}}注意timestamp与服务器时间偏差不能超过10分钟否则报错invalid timestamp。生产环境务必保证NTP时间同步。3.2 一个完整的商品同步调用87个接口里使用频率最高的是商品同步和库存查询。以商品同步为例publicclassGoodsSyncService{privatefinalTokenManagertokenManagernewTokenManager();/** * 同步供应商商品到平台 * method: legendshop.goods.push */publicSyncResultpushGoods(SupplierGoodsgoods){MapString,StringbiznewHashMap();biz.put(supplier_id,goods.getSupplierId());biz.put(outer_goods_id,goods.getOuterId());biz.put(goods_name,goods.getName());biz.put(category_code,goods.getCategoryCode());biz.put(market_price,goods.getMarketPrice().toPlainString());biz.put(supply_price,goods.getSupplyPrice().toPlainString());biz.put(stock,String.valueOf(goods.getStock()));MapString,StringrequestSignUtil.buildRequest(legendshop.goods.push,biz,tokenManager.getToken(),Constants.CLIENT_SECRET);StringresponseHttpUtil.post(Constants.OPEN_API_URL,request);JSONObjectjsonJSON.parseObject(response);// 平台侧的goods_id回写后用于后续订单回传returnnewSyncResult(json.getString(platform_goods_id),json.getInteger(code)0);}}四、回调webhook消息处理供应链侧的库存变化、发货状态要实时通知平台。开放平台用webhook推送需要先在控制台配置回调地址再验签处理PostMapping(/open/callback)publicStringhandleCallback(RequestBodyCallbackMessagemsg){// 1.验签防止伪造回调StringexpectedSignSignUtil.sign(msg.getBizContent(),Constants.CLIENT_SECRET);if(!expectedSign.equals(msg.getSign())){log.warn(非法回调签名不匹配, messageId{},msg.getMessageId());returnfail;}// 2.幂等判断messageId已处理过直接返回成功if(idempotentService.exists(msg.getMessageId())){returnsuccess;}// 3.按消息类型分发处理switch(msg.getType()){caseSTOCK_CHANGED-stockService.updateStock(msg.getBizContent());caseORDER_SHIPPED-logisticsService.onShipped(msg.getBizContent());caseREFUND_FINISHED-refundService.onFinished(msg.getBizContent());default-log.info(忽略消息类型: {},msg.getType());}// 4.记录幂等标记idempotentService.save(msg.getMessageId());returnsuccess;}处理回调有三个铁律验签、幂等、快速返回。回调接口只做落库业务处理丢到MQ异步执行处理慢了平台会重试导致消息堆积。五、87个接口的分类地图按业务域划分87个接口的分布大致是商品域22个商品推送、批量查询、类目映射、价格变更、上下架库存域15个实时库存查询、批量库存、库存锁定、库存变更通知订单域28个订单创建、拆单、发货、取消、退换货、对账单物流域12个运单查询、物流轨迹、运费试算、地址校验基础域10个鉴权、签名验证、字典查询、供应商信息、消息订阅管理实际对接时不必全部接完。按小羊云商的实施经验MVP阶段接商品、库存、订单三个域共约30个接口就能跑通业务闭环其余接口随业务深入逐步接入。六、限流与重试策略开放平台对单应用的限流是100次/秒。触发限流返回错误码10005正确做法是指数退避重试而不是硬刷publicclassRetryExecutor{privatestaticfinalintMAX_RETRY3;publicStringexecuteWithRetry(SupplierStringapiCall){intattempt0;while(true){try{StringresponseapiCall.get();JSONObjectjsonJSON.parseObject(response);if(json.getInteger(code)10005attemptMAX_RETRY){// 限流指数退避 1s, 2s, 4slongsleep1000L*(1Lattempt);Thread.sleep(sleep);attempt;continue;}returnresponse;}catch(InterruptedExceptione){Thread.currentThread().interrupt();thrownewBizException(重试被中断);}}}}踩坑记录订单回传接口偶发超时最初我们用固定间隔重试结果同一笔订单被创建两次。后来改成幂等键分布式锁双保险订单号作为幂等键先查重再执行业务。重试时带上同一个幂等键供应商侧就能识别重复请求。七、对账数据一致性的最后防线接口调用成功不代表数据一致。网络抖动、回调丢失都可能造成平台和供应商两侧数据不一致所以每日对账必不可少/** * 每日凌晨2点对账 * 拉取供应商侧昨日订单与平台侧逐单核对状态和金额 */Scheduled(cron0 0 2 * * ?)publicvoiddailyReconcile(){LocalDateyesterdayLocalDate.now().minusDays(1);ListSupplierOrdersupplierOrdersorderClient.pullOrdersByDate(yesterday);MapString,PlatformOrderplatformMapplatformOrderService.mapByOuterOrderNo(yesterday);ListDiffRecorddiffsnewArrayList();for(SupplierOrderso:supplierOrders){PlatformOrderpoplatformMap.get(so.getOrderNo());if(ponull){diffs.add(DiffRecord.missing(so.getOrderNo()));}elseif(po.getStatus()!so.getStatus()||po.getAmount().compareTo(so.getAmount())!0){diffs.add(DiffRecord.mismatch(so.getOrderNo(),po.getStatus(),so.getStatus()));}}if(!diffs.isEmpty()){// 差异告警人工介入自动补偿有风险alertService.send(对账差异diffs.size()条,diffs);}}八、总结LegendShop开放平台API的对接要点归纳成一句话token缓存好、签名别拼错、回调做幂等、限流用退避、对账每天跑。这87个接口是小羊云商S2B2C平台连接外部供应链的标准化通道把过去一家供应商一套代码的对接模式收敛成了一套规范对接N家的工程化模式也是朗尊软件在供应链数字化方向上持续投入的成果。