连接器设计
柠檬跨境ERP 对接的第三方分为七类,每类是一个独立的 SPI(Java 接口),由 Spring 收集全部实现、按平台或服务商查找。它们沿用同样的思路:
info()声明授权方式、授权字段、正式与沙箱地址、支持的能力和文档地址,页面按声明动态生成授权表单、显示可用的按钮;- 能力之外的方法有默认实现(抛出「不支持」的提示),实现类只写支持的部分;
- 地址一律经上下文取得:配置了自定义地址时用它(测试时指向模拟服务器),否则按环境取正式或沙箱地址;
- 授权信息由框架解密后放在上下文中传给连接器,连接器刷新令牌后通过上下文写回(加密保存);
- 连接器只负责协议(签名、分页、报文转换),写库、事务、重试、日志由调用它的 Service 负责。
渠道连接器 ChannelConnector
包 ecom/connector,按 EcomPlatform 查找(ConnectorRegistry)。
public interface ChannelConnector {
ConnectorInfo info(); // 平台、授权方式、授权字段、地址、能力、文档
// 授权(OAuth 平台实现)
default String authorizeUrl(ConnectorContext ctx, String redirectUri, String state) { ... }
default OAuthResult exchangeCode(ConnectorContext ctx, Map<String, String> params, String redirectUri) { ... }
default void ensureToken(ConnectorContext ctx) { } // 刷新令牌后 ctx.updateCredentials(...) 加密写回
default void test(ConnectorContext ctx) { ... } // 测试授权,默认拉取最近一天的订单
// 能力
List<OrderDraft> fetchOrders(ConnectorContext ctx, LocalDateTime since); // ORDERS
default ShipmentResult confirmShipment(ConnectorContext ctx, EcomOrder order, List<EcomOrderItem> items) { ... } // SHIP_CONFIRM
default boolean partialShipment() { return false; } // 是否按包裹部分回传
default void pushInventory(ConnectorContext ctx, List<InventoryUpdate> updates) { ... } // INVENTORY_PUSH
default List<ListingDraft> fetchListings(ConnectorContext ctx) { ... } // LISTINGS
}ConnectorInfo:AuthType(OAUTH/KEYS)、授权字段CredentialField(text、secret、token、oauthInfo、cached几种,敏感字段为密码框、OAuth 字段只读、缓存字段如访问令牌不显示)、正式 / 沙箱地址、能力ConnectorCapability(ORDERS、SHIP_CONFIRM、INVENTORY_PUSH、LISTINGS、PLATFORM_STOCK);可选perStoreBaseUrl(每店域名不同,如 Shopify)、回调地址说明、拉单时间窗说明、增量回看小时数。ConnectorContext:店铺、解密后的授权StoreCredentials、是否沙箱、自定义地址;baseUrl(info)取地址,updateCredentials(changes)写回令牌。- 公共工具:
HttpJson(JDK HttpClient 的 JSON 请求)、ConnectorSigns(HMAC / MD5 等签名)、ConnectorHttpException。
已实现的平台:
| 平台 | 实现类 | 授权 | 说明 |
|---|---|---|---|
| 亚马逊 | AmazonSpConnector | 密钥(LWA 刷新令牌) | SP-API,按 region 选网关,含静态沙箱 |
| 速卖通 | AliExpressConnector | 密钥 | 开放平台 TOP 协议 |
| 虾皮 Shopee | ShopeeConnector | OAuth | 官方沙箱,商户 / 店铺级签名 |
| Lazada | LazadaConnector | OAuth | 按站点选网关 |
| TikTok Shop | TikTokShopConnector | OAuth | Partner Center 测试店铺 |
| Temu | TemuConnector | 密钥 | 半托管 / 本土卖家,按区域选网关 |
| eBay | EbayConnector | OAuth | 沙箱 api.sandbox.ebay.com |
| Shopify | ShopifyConnector | 密钥(访问令牌) | Admin GraphQL,每店域名不同 |
| 沃尔玛 | WalmartConnector | 密钥 | 沙箱 sandbox.walmartapis.com |
| Ozon | OzonConnector | 密钥 | FBS / FBO |
| 美客多 | MercadoLibreConnector | OAuth |
部分发货回传(partialShipment() 为 true):亚马逊、eBay、Shopify、TikTok Shop、沃尔玛、Temu;其他平台全部包裹发完后整单回传一次。使用平台物流的(Lazada、虾皮 SLS、Ozon、美客多 me2)运单号由平台生成,回传发货后带回平台运单号。
联调状态
各连接器均按平台官方公开文档实现,每个都有模拟服务器单元测试(验证签名、授权、分页、报文与错误),尚未用真实开发者账号联调。各连接器的 javadoc 中列出了需要核对的点,正式接入前请用自己的开发者账号验证。
刊登连接器 PublishConnector
包 ecom/publish/connector,与订单连接器分开但复用店铺授权(调用前先由订单连接器 ensureToken)。能力 PublishCapability:CATEGORIES、ATTRIBUTES、PUBLISH、OFFLINE、PRICE、COMPETITIVE_PRICE;方法 categories、attributes、publish(PublishPayload → PublishResult:成功 / 处理中 / 失败)、checkPublish(异步平台查询结果)、offline、updatePrices、competitivePrices;PublishSupport 提供图片下载与 multipart 上传。11 个平台都有实现(亚马逊 Listings Items + Product Type Definitions、eBay Inventory API、Shopify productSet、沃尔玛 MP_ITEM feed、Ozon import 等)。
客服连接器 MessageConnector
包 ecom/cs/connector:能力 CsCapability,方法 fetchThreads、sendMessage、markRead、fetchReviews、replyReview、requestReview(请求评价)。已实现虾皮聊天、TikTok Shop 客服、亚马逊请求评价(Solicitations);亚马逊买家消息平台不开放,TikTok 评价只能导入。
广告连接器 AdsConnector
包 ecom/ads:AdsConnectorInfo 声明授权字段、能力 AdsCapability(PROFILES、STRUCTURE、REPORTS、UPDATE_BID、UPDATE_BUDGET、UPDATE_STATE、NEGATIVE_KEYWORDS)、最低竞价、可拉取的报告类型、一次报告最多天数;方法 ensureToken、test、profiles、fetchStructure、fetchReports(异步报告由连接器内部完成创建 → 轮询 → 下载)、applyChanges(逐项返回结果)、createNegativeKeywords、OAuth 的 authorizeUrl / exchangeCode,以及按广告类型和层级判断能力的 supports(adType, level, capability)。已实现 AmazonAdsConnector(SP)+ AmazonAdsSbSd(SB、SD)。
物流商连接器 CarrierConnector
包 ecom/carrier,按 EcomCarrier 查找(CarrierRegistry),授权填在物流渠道上:
public interface CarrierConnector {
EcomCarrier carrier();
CarrierInfo info(); // 授权字段 CarrierField、正式 / 测试地址
CarrierWaybill createOrder(CarrierContext ctx, CarrierShipment shipment); // 下单取号,返回运单号与面单
byte[] label(CarrierContext ctx, CarrierWaybill waybill); // 面单 PDF
void cancel(CarrierContext ctx, CarrierWaybill waybill); // 取消运单
List<CarrierTrackEvent> track(CarrierContext ctx, String trackingNo); // 轨迹
default CarrierTrackInfo trackInfo(CarrierContext ctx, String trackingNo) { ... } // 轨迹 + 归一状态
}已实现 4PX 递四方(MD5 签名)和云途 YunExpress(Basic 认证);没有对接或查不到轨迹时用 SeventeenTrackClient(17TRACK API v2.2),状态由 TrackStatusNormalizer 归一为 EcomTrackStatus。
海外仓连接器 OwhConnector
包 ecom/owh/connector,按 OwhProvider 查找(OwhRegistry),授权在海外仓账号上。方法:warehouses、products(物流产品)、inventory、createInbound / queryInbound、createOutbound / queryOutbound / cancelOutbound、fees、createReturn / queryReturn、createTransferOut / queryTransferOut、cancelInbound / cancelReturn;能力 OwhCapability 决定页面是否显示对应操作(如万邑通没有作废退件单的接口,页面显示「标记已作废」)。已实现谷仓 GoodcangConnector、万邑通 WinitConnector、4PX 海外仓 FourPxFb4Connector。
1688
包 ecom/dev/ali1688:Ali1688Signer(param2/1/{namespace}/{name}/{appKey} + 排序参数,HMAC-SHA1 转大写十六进制)与 Ali1688Client(商品详情、fastCreateOrder 下单、订单详情与物流、支付链接、取消)。授权为 OAuth,回调 /api/ecom/oauth/callback/alibaba1688。
扩展方法见 新增平台连接器 与 新增海外仓 / 物流商。