多平台多店铺接入
一套系统可以管理多个平台、每个平台多个站点和店铺。每个店铺单独保存平台、站点、币种、授权信息和接口环境;系统调用平台接口时按店铺取授权,自动拉取订单和在线商品、回传发货和库存。本页说明各平台的授权方式、沙箱环境和回调地址的配置,店铺的全部字段见平台店铺。

接入能做什么
| 能力 | 说明 | 频率 |
|---|---|---|
| 拉取订单 | 增量拉取最近更新的订单(上次同步时间往前重叠 2 小时,避免遗漏),按「店铺 + 平台订单号」去重,重复拉取不会重复入库 | 定时每 30 分钟;店铺上可手工「同步订单」并指定起始时间 |
| 回传发货 | 订单发货后把承运商和运单号回传平台;平台物流托管的订单由平台生成运单号并带回系统 | 发货后立即 |
| 回传库存 | 自发货、在售、已配对的在线商品:可售 = 默认发货仓空闲库存 ÷ 多件装(向下取整)− 保留数量,只回传有变化的 | 定时每 15 分钟(店铺开启「自动回传库存」时);可手工回传 |
| 拉取商品 | 拉取平台在线商品,不覆盖已有的配对;平台 SKU 等于物料编码时自动配对 | 定时每天;可手工「同步商品」 |
| 令牌维护 | 快过期的 OAuth 令牌自动刷新,刷新失败的店铺标记为「需重新授权」 | 定时每小时 |
所有调用都记录在同步日志中(保留 90 天),在店铺行的「同步日志」或渠道接入中查看。
注意
各平台接口都按官方公开文档实现,并有模拟服务器单元测试,但尚未用真实开发者账号联调。接入自己的店铺时,请先在沙箱或测试店铺上验证拉单、回传,确认无误后再切换到正式环境、开启自动同步。
两种授权方式
编辑店铺时,选择平台后表单的「渠道接口」区域会显示该平台的授权方式、支持的能力、开发者文档、回调地址说明和订单同步说明,「授权信息」中的输入框也按平台自动生成。
| 方式 | 平台 | 操作 |
|---|---|---|
| 填写密钥 | 亚马逊、速卖通、Temu、Shopify、沃尔玛、Ozon | 在平台卖家后台或开发者后台生成密钥 / 令牌,填写到「授权信息」中保存,再点行操作「测试授权」验证 |
| OAuth 授权 | 虾皮、Lazada、TikTok Shop、eBay、美客多 | 先填写应用的 App Key / Client ID 等并保存店铺,再点行操作「授权」,在新窗口登录平台并同意授权;平台回调后系统换取令牌,自动回填 Shop ID 等信息并定时刷新 |


授权信息的保存规则:
- 授权信息用 AES-256-GCM 加密保存,只写不读:保存后输入框显示「已设置,留空表示不修改」,任何页面和接口都不会返回明文。
- 修改店铺时留空的字段保持原值,OAuth 令牌始终保留;要彻底清除,点授权区域的「清除授权」。
- OAuth 令牌、Shop ID 等由授权回调写入的字段在表单中只读显示(未授权 / 已授权)。
- 更换了系统的 JWT 密钥(
lemon.jwt.secret)后,已保存的授权无法解密,需要重新填写或重新授权。
各平台授权说明
| 平台 | 授权方式 | 需要填写 | 沙箱 / 测试 | 说明 |
|---|---|---|---|---|
| 亚马逊 | 填写密钥 | 区域(NA / EU / FE)、Marketplace ID、LWA Client ID、LWA Client Secret、Refresh Token;卖家 ID 可选(店铺已填卖家 ID 时可不填) | 静态沙箱(sandbox.sellingpartnerapi-na.amazon.com 等,按区域) | Selling Partner API。getOrders 限速约每分钟 1 次,自动同步间隔不要短于默认的 30 分钟 |
| 速卖通 | 填写密钥 | App Key、App Secret、Access Token | 无单独沙箱 | 开放平台 TOP 协议 |
| 虾皮 Shopee | OAuth | Partner ID、Partner Key、站点(用于商品链接,可选) | 官方沙箱 partner.test-stable.shopeemobile.com | 订单列表每次最多查 15 天,同步时自动按 15 天分段;虾皮 SLS 物流由平台生成运单号,揽收需在卖家中心安排 |
| Lazada | OAuth | App Key、App Secret、站点(SG / MY / TH / PH / VN / ID)、打包分配方式(本地店铺 TFS / 跨境店铺 NTFS,默认 TFS) | 用 Lazada 测试店铺 | 按站点选网关;平台物流由平台生成运单号 |
| TikTok Shop | OAuth | App Key、App Secret、Service ID(服务市场应用);回传库存的仓库 ID 可选 | 用 Partner Center 测试店铺 | 授权后自动写入 Shop ID、Shop Cipher、卖家名称 |
| Temu | 填写密钥 | 区域(US / EU / GLOBAL)、App Key、App Secret、Access Token | 无单独沙箱 | 适用于半托管 / 本土卖家,按区域选网关 |
| eBay | OAuth | App ID(Client ID)、Cert ID(Client Secret)、RuName(回调地址名称) | 沙箱 api.sandbox.ebay.com | 回调地址不是 URL 而是 RuName,见下文 |
| Shopify | 填写密钥 | 店铺域名(xxx.myshopify.com)、Admin API 访问令牌;库存地点 ID 可选(默认主地点) | 用开发商店 | Admin GraphQL,每个店铺的接口地址就是自己的店铺域名 |
| 沃尔玛 | 填写密钥 | Client ID、Client Secret;发货节点 ID(Ship Node)可选 | 沙箱 sandbox.walmartapis.com | 访问令牌由系统自动获取并缓存 |
| Ozon | 填写密钥 | Client ID、API 密钥;FBS 仓库 ID(回传库存时必填) | 无单独沙箱 | 支持 FBS / FBO。货件列表只能按创建时间过滤,定时同步会额外回看 7 天更新近期货件的状态,更早的需手工指定起始时间同步 |
| 美客多 | OAuth | App ID(Client ID)、Client Secret、站点(MLM / MLB / MLA 等) | 无单独沙箱 | 回调地址必须与应用后台登记的 Redirect URI 完全一致;me2 物流由平台生成运单号 |
选择「其他」平台的店铺没有接口,订单、商品通过 Excel 导入。
接口环境
| 字段 | 说明 |
|---|---|
| 环境 | 「正式」或「沙箱 / 测试」。下方提示当前环境的默认接口地址;没有沙箱地址的平台在测试环境下仍使用正式地址,需配合平台的测试店铺使用 |
| 自定义接口地址 | 私有网关或测试用的模拟服务器地址,留空按环境使用默认地址。演示店铺填的是本机不可用的地址 http://127.0.0.1:9,因此不会访问真实平台 |
| 自动同步订单 / 自动回传库存 | 在店铺「自动同步」区域开启后,定时任务才会处理该店铺 |
回调地址(OAuth 平台)
OAuth 平台授权完成后,平台会跳转回系统的回调地址:
<后端地址>/api/ecom/oauth/callback/<平台><平台> 分别为 shopee、lazada、tiktok、ebay、mercado_libre。例如后端外网地址为 https://erp.example.com,虾皮的回调地址就是 https://erp.example.com/api/ecom/oauth/callback/shopee。回调接口不需要登录,系统按签名的授权参数识别租户和店铺,授权链接 30 分钟内有效。
各平台的登记方式:
| 平台 | 在平台开发者后台怎么填 |
|---|---|
| 虾皮 | 在开放平台的应用设置中登记本系统后端的域名(虾皮校验回调地址的域名) |
| Lazada | 在应用管理中把 Callback URL 设为回调地址 |
| TikTok Shop | 不使用授权链接中的回调地址:在 Partner Center 的应用设置中把 Redirect URL 配置为回调地址 |
| eBay | 回调地址不是 URL 而是 RuName:在 eBay 开发者后台「User Tokens」中把该 RuName 的 Your auth accepted URL 设为回调地址,再把 RuName 填到店铺授权信息中 |
| 美客多 | 应用后台登记的 Redirect URI 必须与回调地址完全一致 |
部署在反向代理后面时
系统默认按当前请求推算回调地址。部署在 Nginx 等反向代理之后、或对外域名与内部地址不同时,需要配置后端的外网地址:在 application.yml 中设置 lemon.ecom.public-url(或环境变量 LEMON_ECOM_PUBLIC_URL),值为包含 /api 的后端外网地址,如 https://erp.example.com/api,并确保该地址能被平台访问到。
接入一个新店铺的步骤
- 在「财务管理 → 期末与设置 → 币种汇率」中确认店铺的结算币种和当月汇率已存在。
- 打开「运营管理 → 店铺管理 → 平台店铺」,点「新增店铺」,填写编码、名称、平台、站点、币种、时区、负责人、默认发货仓、平台仓等。
- 在「授权信息」中填写平台要求的字段;首次接入建议选择「沙箱 / 测试」环境,暂不开启自动同步。保存。
- 填写密钥的平台点行操作「测试授权」;OAuth 平台点「授权」,在弹出的平台页面登录并同意,回到系统后授权状态变为「已授权」。
- 点「同步订单」(可指定起始时间)、更多菜单中的「同步商品」,在「同步日志」中检查结果。
- 验证无误后把环境切换为「正式」(重新授权),开启「自动同步订单」和「自动回传库存」。
- 在渠道接入中查看各店铺的授权状态、各接口最近一次结果和 24 小时失败次数。

其他外部服务
除销售平台外,以下服务也在系统中授权,授权信息同样加密保存、只写不读:
| 服务 | 配置位置 | 授权方式与回调地址 |
|---|---|---|
| Amazon Ads(广告) | 运营管理 → 广告管理 → 广告数据 中的广告授权 | Login with Amazon OAuth:填写广告应用的区域、Client ID、Client Secret,点「使用 Amazon 账号授权」;回调地址 <后端地址>/api/ecom/oauth/callback/amazon-ads |
| 谷仓、万邑通、4PX 海外仓 | 物流管理 → 海外仓 → 海外仓账号 | 填写服务商的密钥 / 令牌,可选测试环境和自定义地址,「测试授权」拉取仓库列表;关闭「自动同步」后定时任务跳过该账号 |
| 4PX 递四方、云途(物流下单) | 物流管理 → 头程物流 → 物流渠道 | 在物流渠道上选择对接的物流商并填写授权、环境,用于申请运单号、取面单、查轨迹 |
| 17TRACK(轨迹查询) | 订单管理 → 订单处理 → 物流跟踪 → 跟踪设置 | 填写 17TRACK 密钥,没有对接物流商的运单号用它查询轨迹 |
| 1688 | 供应链 → 1688 采购 → 1688 账号 | OAuth:填写 AppKey、AppSecret 后授权;回调地址 <后端地址>/api/ecom/oauth/callback/alibaba1688 |