marketplace-connectors

市场平台连接器

概述

在 Amazon、eBay 和 Walmart Marketplace 上销售可以扩大销售渠道的覆盖范围，但也会增加运营复杂性：每个市场平台都有自己的产品数据模型、商品刊登要求、订单生命周期和库存管理 API。本技能介绍如何将商店连接到主要市场平台——托管平台使用应用，自定义店面则采用直接 API 集成。

何时使用本技能

• 将销售渠道从自有店面扩展到主要市场平台时
• 构建跨渠道同步库存的多渠道电商系统时
• 将市场平台订单导入 OMS 或 ERP 的流程自动化时
• 现有市场平台商品信息馈送依赖手动操作（上传电子表格），需要实现自动化时

核心说明

第 1 步：确定平台和建议的方案

平台	建议方案	主要应用
Shopify	使用市场平台应用，无需自定义代码	Codisto（$39/月），支持 Amazon + eBay + Walmart；LitCommerce（$19/月），用于多渠道商品刊登管理
WooCommerce	使用插件进行标准集成	WooCommerce Amazon Fulfillment（免费，amazon.com），用于 FBA；WP-Lister Pro for Amazon（$99），用于完整的商品刊登和订单管理
BigCommerce	使用应用市场连接器	Sellbrite（$79/月，marketplace.bigcommerce.com）可同步 Amazon、eBay、Walmart 和 Etsy；ChannelAdvisor 用于企业级多渠道管理
自定义 / 无头架构	直接进行 API 集成	使用 Amazon SP-API、eBay REST API 和 Walmart Marketplace API 构建；使用队列导入订单并同步库存

第 2 步：按平台设置市场平台

---

Shopify

使用 Codisto 连接 Amazon：

1. 从 Shopify App Store 安装 Codisto（Amazon + eBay 套餐为 $39/月）
2. 连接你的 Amazon Seller Central 账户（支持美国、英国、欧盟和澳大利亚）
3. 在 Codisto 中，前往 Listings → Amazon，然后点击 Link Products——它会将 Shopify 产品与现有 ASIN 匹配，或创建新的商品刊登
4. 启用 Inventory Sync，在 Shopify 库存变化时自动更新 Amazon 库存数量
5. 启用 Order Import——Codisto 会将 Amazon 订单导入为 Shopify 订单，让你可以在同一处管理履约

刊登前的重要事项：

• 在 Codisto 设置中设置安全库存缓冲：将 Shopify 库存的 10–20% 保留，不供市场平台销售，以避免同步延迟导致超卖
• 在 Codisto 中配置各市场平台的定价，以计入 Amazon 费用（15% 推荐费 + FBA 费用）——价格应高于 Shopify 商店

---

WooCommerce

使用 WP-Lister Pro 连接 Amazon：

1. 购买并安装 WP-Lister Pro for Amazon（从 wp-lister.com 购买，$99）
2. 前往 WP-Lister → Settings → Amazon，输入 Amazon Marketplace Web Service (MWS) 凭据
3. 在 WP-Lister → Products 中，选择要刊登的产品，并配置 ASIN 匹配或创建新的商品刊登
4. 启用 Auto-sync inventory——WooCommerce 库存变化时，WP-Lister 会更新 Amazon 库存数量
5. 启用 Import Amazon orders——订单会自动显示在 WooCommerce 中

在 WooCommerce 上连接 eBay：

1. 安装 WP-Lister Pro for eBay（$99）——操作流程与 Amazon 版本相同
2. 在 WP-Lister 设置中使用 eBay API 凭据进行连接
3. 配置 WooCommerce 分类与 eBay 分类之间的分类映射

---

BigCommerce

使用 Sellbrite 连接 Amazon、eBay 和 Walmart：

1. 从 BigCommerce App Marketplace 安装 Sellbrite（79 美元/月）
2. 连接你的市场卖家账户（Amazon、eBay、Walmart）和 BigCommerce 商店
3. Sellbrite 获取你的 BigCommerce 产品目录，并将商品信息同步到所有已连接的市场
4. 为每个渠道设置库存缓冲规则（例如，为你的 BigCommerce 商店预留 5 件库存）
5. 配置自动导入订单 — 市场订单会显示在 BigCommerce 中，便于统一履约

---

Custom / Headless

Amazon SP-API 身份验证：

// lib/amazon/auth.ts — LWA OAuth token with caching
let tokenCache: { accessToken: string; expiresAt: number } | null = null;

export async function getAccessToken(): Promise<string> {
  if (tokenCache && tokenCache.expiresAt > Date.now() + 60000) return tokenCache.accessToken;

  const res = await fetch('https://api.amazon.com/auth/o2/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'refresh_token',
      refresh_token: process.env.AMAZON_REFRESH_TOKEN!,
      client_id: process.env.AMAZON_CLIENT_ID!,
      client_secret: process.env.AMAZON_CLIENT_SECRET!,
    }),
  });

  const data = await res.json();
  tokenCache = { accessToken: data.access_token, expiresAt: Date.now() + data.expires_in * 1000 };
  return tokenCache.accessToken;
}

更新 Amazon 库存（SP-API Listings Items）：

export async function updateAmazonInventory(sellerId: string, sku: string, quantity: number) {
  const accessToken = await getAccessToken();
  // SP-API also requires AWS Signature V4 — use @smithy/signature-v4
  return fetch(`https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/${sellerId}/${encodeURIComponent(sku)}`, {
    method: 'PATCH',
    headers: { 'x-amz-access-token': accessToken, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      productType: 'PRODUCT',
      patches: [{ op: 'replace', path: '/attributes/fulfillment_availability', value: [{
        fulfillment_channel_code: 'DEFAULT',
        quantity,
        marketplace_id: 'ATVPDKIKX0DER', // US marketplace
      }] }],
    }),
  });
}

导入 Amazon 订单（每 5 分钟轮询一次）：

export async function pollAmazonOrders() {
  const lastPolledAt = await db.syncState.getLastPolled('amazon') ?? new Date(Date.now() - 3_600_000);
  const accessToken = await getAccessToken();

  const params = new URLSearchParams({
    MarketplaceIds: 'ATVPDKIKX0DER',
    CreatedAfter: lastPolledAt.toISOString(),
    OrderStatuses: 'Unshipped,PartiallyShipped',
  });

  const res = await fetch(`https://sellingpartnerapi-na.amazon.com/orders/v0/orders?${params}`, {
    headers: { 'x-amz-access-token': accessToken },
  });
  const { payload } = await res.json();

  for (const amazonOrder of payload.Orders ?? []) {
    // Idempotent: skip if already imported
    if (await db.orders.findByExternalId(amazonOrder.AmazonOrderId)) continue;

    await orderQueue.add('import-order', {
      externalId: amazonOrder.AmazonOrderId,
      channel: 'amazon',
      // ...map order fields
    }, { jobId: `amazon-${amazonOrder.AmazonOrderId}` });
  }

  await db.syncState.updateLastPolled('amazon', new Date());
}

库存变更时跨所有渠道同步库存：

export async function syncInventoryAcrossChannels(sku: string, quantity: number, source: string) {
  const tasks = [];

  if (source !== 'amazon') {
    tasks.push(updateAmazonInventory(process.env.AMAZON_SELLER_ID!, sku, quantity)
      .catch(err => console.error(`Amazon sync failed for ${sku}:`, err)));
  }

  if (source !== 'ebay') {
    tasks.push(ebayClient.updateInventoryItem(sku, quantity)
      .catch(err => console.error(`eBay sync failed for ${sku}:`, err)));
  }

  // Run all syncs in parallel; individual failures logged but don't block others
  await Promise.allSettled(tasks);
}

最佳实践

• 为每个渠道设置安全库存缓冲 — 切勿将 100% 的库存开放给各个市场；为自有商店预留库存，并留出空间以应对同步延迟
• 实现幂等的订单导入 — 使用市场订单 ID 作为唯一键；轮询可能多次返回同一订单；唯一约束可防止重复
• 及时确认市场订单 — Walmart 要求在 4 小时内确认；Amazon 要求在承诺的配送 SLA 内确认发货；延迟响应会影响账户缺陷指标
• 遵守各市场的速率限制 — Amazon SP-API 对每种操作使用令牌桶限制；批量更新库存（数千个 SKU）时，使用指数退避策略和 Feeds API，而不是逐项调用
• 监控商品信息健康状况，而不只是同步状态 — 按市场跟踪商品信息的隐藏情况、购物车赢得率和账户健康状况；商品信息被隐藏会造成收入损失

常见问题

问题	解决方案
Amazon 商品信息发布成功，但变为非活跃状态	检查 Listings API 响应中的商品信息隐藏情况；常见原因包括缺少该产品类型所需的属性
库存因同步延迟而超卖	在市场应用设置中设置安全库存缓冲；结账时始终进行最终库存检查
SP-API 返回 QuotaExceeded	每种 SP-API 操作都有独立的速率限制；使用 Feeds API 批量更新库存，而不是逐项调用 PATCH
Shopify 市场应用未导入订单	在 Shopify 管理后台的 Apps → App permissions 中，检查该应用是否具有 Orders 的 Write 权限
eBay 商品信息因违反政策而被拒	自动化之前，先检查商品标题中是否包含受限词语；查看 eBay 的 Prohibited Items 政策

相关技能

• @webhook-architecture
• @product-information-management
• @erp-integration
• @monitoring-alerting-commerce