Skip to content

连接器设计 ​

柠檬跨境ERP 对接的第三方分为七类,每类是一个独立的 SPI(Java 接口),由 Spring 收集全部实现、按平台或服务商查找。它们沿用同样的思路:

  • info() 声明授权方式、授权字段、正式与沙箱地址、支持的能力和文档地址,页面按声明动态生成授权表单、显示可用的按钮;
  • 能力之外的方法有默认实现(抛出「不支持」的提示),实现类只写支持的部分;
  • 地址一律经上下文取得:配置了自定义地址时用它(测试时指向模拟服务器),否则按环境取正式或沙箱地址;
  • 授权信息由框架解密后放在上下文中传给连接器,连接器刷新令牌后通过上下文写回(加密保存);
  • 连接器只负责协议(签名、分页、报文转换),写库、事务、重试、日志由调用它的 Service 负责。

渠道连接器 ChannelConnector ​

包 ecom/connector,按 EcomPlatform 查找(ConnectorRegistry)。

java
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 协议
虾皮 ShopeeShopeeConnectorOAuth官方沙箱,商户 / 店铺级签名
LazadaLazadaConnectorOAuth按站点选网关
TikTok ShopTikTokShopConnectorOAuthPartner Center 测试店铺
TemuTemuConnector密钥半托管 / 本土卖家,按区域选网关
eBayEbayConnectorOAuth沙箱 api.sandbox.ebay.com
ShopifyShopifyConnector密钥(访问令牌)Admin GraphQL,每店域名不同
沃尔玛WalmartConnector密钥沙箱 sandbox.walmartapis.com
OzonOzonConnector密钥FBS / FBO
美客多MercadoLibreConnectorOAuth

部分发货回传(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),授权填在物流渠道上:

java
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。

扩展方法见 新增平台连接器 与 新增海外仓 / 物流商。

面向跨境电商卖家的开源 ERP · 基于 GPL-3.0 协议
联系我们:电话 17701123202 · 微信 BG7LIF · 邮箱 zmissu@163.com