做跨境系统，绕不开和各大海外电商平台的 API 打交道。这篇把 Amazon、Shopee、Lazada、TikTok Shop、AliExpress、Temu 六大平台的对接门槛、鉴权差异、限流规则、高频坑一次讲透，并给出一套「多平台统一适配层」的架构方案——这是把对接成本从 N 倍降回 1 倍的关键。
一、先认清现实：对接的三大难点
海外平台 API 和国内平台比，难点不在「接口多」，而在门槛高、鉴权杂、规则散：
- 门槛高：多数平台要求企业资质，Amazon 还要求法人视频验证、水电账单，审核动辄 1~2 周；
- 鉴权杂：LWA OAuth 2.0、Access Token、签名校验、OAuth 1.0a 并存，每家流程都不一样；
- 规则散：限流按「桶+速率」双限制、字段命名各家一套、时区货币各玩各的。
选型建议：先明确业务市场（欧美 or 东南亚），再挑 2~3 个平台主攻。别贪多——每多接一个平台，都是长期的维护成本。
二、鉴权：四套体系，一个策略搞定
Token 管理的三个工程要点：
// 1. Token 刷新要加分布式锁，防止多实例并发刷新互相踢掉 public synchronized String getAccessToken(String platform, String shopId) { TokenCache cache = tokenRepo.get(platform, shopId); // 提前 30 分钟刷新，避免"临界过期"导致请求失败 if (cache == null || cache.expireAt - now() < 30 * 60 * 1000L) { cache = refreshClient.refresh(cache.refreshToken); tokenRepo.save(platform, shopId, cache); } return cache.accessToken; } // 2. 刷新失败必须告警 + 兜底重试，别让半夜过期搞挂全量任务 // 3. refresh_token 按平台要求加密落库，明文进 Git 等于裸奔
授权链路注意：Amazon/Shopee 采用「卖家点击授权 → 回调拿授权码 → 换 Token」的流程，回调域名必须 HTTPS 且与平台登记一致，这个细节能卡住一大批人一整天。
三、限流：出海平台比国内严得多
各平台普遍采用双维度限流（令牌桶容量 burst + 每秒补充速率 rate），且按接口粒度分配。超限返回 429 或特定错误码，处理不当会雪崩：
// 指数退避 + 抖动：被限流后的标准姿势 public <T> T callWithBackoff(Supplier<T> call) { for (int i = 0; i < 5; i++) { try { return call.get(); } catch (RateLimitException e) { long wait = (long) (Math.pow(2, i) * 1000 + random.nextInt(500)); sleep(wait); // 1s, 2s, 4s, 8s... 每次加随机抖动 } } throw new RuntimeException("重试 5 次仍被限流，降级处理"); }
三条铁律：
- 客户端自己也限流——按平台给的配额做本地令牌桶，别把配额耗在 429 上；
- 批量接口优先——Amazon 的批量接口一次拉 100 单，比循环单查省 99% 的配额；
- 错峰调度——全量同步任务放到平台流量低谷（注意是目标市场的低谷，不是你的）。
四、多平台对接：别为每个平台写一套代码
接第二个平台时你就会发现：Shopee 的订单状态叫 order_status，TikTok 叫 order_status 但枚举值完全不同，Amazon 叫 OrderStatus 且大小写又不一样。直接在各平台接口上写业务逻辑，代码会迅速烂掉。
// 面向接口编程：业务层永远只依赖这个抽象 public interface PlatformAdapter { UnifiedOrder getOrder(String platform, String orderId); // 归一化订单 List<UnifiedProduct> searchProducts(ProductQuery query); // 归一化商品 void syncInventory(String platform, List<Inventory> items); // 统一库存口径 } // 平台差异在适配器内部消化： // - TikTok 的 "AWAITING_SHIPMENT" == 统一模型的 "PAID_UNSHIPPED" // - Amazon 的 "Shipped" == 统一模型的 "SHIPPED" // - Shopee 的 "READY_TO_SHIP" == 统一模型的 "PAID_UNSHIPPED"
归一化的两个重点：
- 状态机映射表：为每个平台建「平台状态 → 统一状态」映射表，新平台只需配表；
- 公共能力下沉：限流、重试、签名、日志审计做成独立组件，所有适配器复用——这就是上一篇《接口优化》讲的连接池与限流熔断在多平台场景的直接落地。
五、对接落地：实际要跑完这五关
| 阶段 | 关键动作 | 常见卡点 |
| 1. 资质审核 | 企业执照、法人验证、平台入驻 | 材料不齐反复补件 |
| 2. 应用创建 | 创建应用、配置回调、走通授权 | 回调域名 HTTPS 不匹配 |
| 3. 沙箱联调 | 用测试店铺跑通下单→发货→对账主流程 | 沙箱数据与生产不同步 |
| 4. 上线审核 | 提交审核、按类目申请限流配额 | 用例覆盖不全被驳回 |
| 5. 生产灰度 | 小流量试跑、双写对账、逐步放量 | 直接全量，出错难回滚 |
六、六个最耗时间的坑（血泪清单）
逐个给解法：
- 时区与货币：数据库一律存 UTC 时间 + 币种代码 + 原始金额，展示层才做时区和汇率转换。金额用整数分（cent）存储，浮点数算钱必出账目差错；
- 限流退避：见第三章，指数退避 + 抖动 + 本地令牌桶；
- Token 兜底：定时任务提前刷新 + 刷新失败告警 + 手动授权的应急入口；
- 幂等性：所有写操作带客户端幂等键（如
平台订单号+操作类型的哈希），重试前先查本地是否已成功； - 状态语义：别信字段名，逐个核对官方文档的状态机定义，用第四章的映射表消化；
- 沙箱差异：沙箱只能验证「通不通」，上线后第一周必须开启对账任务，用平台 Webhook 推送和拉取接口双通道核对数据一致性。
七、对接自查清单（发版前过一遍）
【资质】开发者账号/应用审核状态正常？授权未过期？ 【凭证】Token 自动刷新 + 提前量 + 失败告警三件套齐了？ 【限流】本地令牌桶按配额配置？429 退避 + 抖动已上线？ 【幂等】写接口全部携带幂等键？重试不会重复发货？ 【时区】全链路 UTC？金额用整数分存储带币种？ 【映射】平台状态→统一状态映射表已配置并评审？ 【对账】Webhook + 拉取双通道对账任务已开启？ 【兜底】平台接口挂掉的降级方案（缓存/人工流程）演练过？
写在最后：出海 API 对接，技术只占三成，剩下七成是 流程管理——资质、审核、配额、对账，每一环都要提前规划。把鉴权收敛成统一策略、把平台差异关进适配层，你就能用一套代码接遍主流平台。
