商品导入

将 Shopify、Amazon、Etsy 及其他电商平台的商品导入您的 Mobazha 店铺。

概述

本功能帮助您将现有平台上的商品列表迁移或复制到 Mobazha。支持两种方式：

• 批量导入（推荐） — 将商品打包为包含 JSON 文件与图片的 ZIP 包，并通过单次调用完成上传
• 单个创建 — 通过 Admin API 逐条创建商品列表

通过 MCP 工具进行批量导入

若店铺已通过 MCP 连接，请使用 listings_import_json 工具实现最快批量导入：

{
  "import_json": "{"listings":[...], "shippingProfiles":[...]}",
  "images_base64": "{"photo1.jpg":"","photo2.jpg":""}"
}

该工具在内部构建 ZIP 归档包，并将其上传至 POST /v1/listings/import/json。

import_json 数据结构

{
  "listings": [
    {
      "slug": "unique-product-slug",
      "title": "商品名称",
      "contractType": "PHYSICAL_GOOD",
      "price": "29.99",
      "pricingCurrency": "USD",
      "description": "商品描述",
      "shortDescription": "简要摘要",
      "productType": "服装",
      "tags": ["tag1", "tag2"],
      "condition": "NEW",
      "nsfw": false,
      "images": ["photo1.jpg", "photo2.jpg"],
      "introVideo": "demo.mp4",
      "processingTime": "1-3 个工作日",
      "grams": 500,
      "quantity": "100",
      "shippingProfileId": "Standard Shipping",
      "variants": [
        { "selections": {"Color": "Red", "Size": "S"}, "price": "24.99", "quantity": "50", "productID": "SKU-RED-S" },
        { "selections": {"Color": "Blue", "Size": "S"}, "price": "26.99", "quantity": "30", "productID": "SKU-BLU-S" }
      ]
    }
  ],
  "shippingProfiles": [
    {
      "key": "Standard Shipping",
      "name": "Standard Shipping",
      "isDefault": true,
      "locationGroups": [
        {
          "name": "Worldwide",
          "locations": [{ "country": "ALL" }],
          "shippingOptions": [
            { "name": "Standard", "type": "FIXED_PRICE", "price": "5.00" }
          ]
        }
      ]
    }
  ],
  "collections": [
    {
      "title": "夏季系列",
      "description": "精选夏季商品",
      "image": "summer-banner.jpg",
      "products": ["unique-product-slug"]
    }
  ],
  "profile": {
    "name": "店铺名称",
    "about": "店铺介绍",
    "shortDescription": "简短标语",
    "location": "New York, US"
  }
}

合约类型

变体

每个变体使用 selections 映射（而非独立的 name/options 字段）：

{ "selections": {"Color": "Red", "Size": "M"}, "price": "24.99", "quantity": "50", "productID": "SKU-001" }

商品分组（Collections）

通过引用商品 slug 将其归入分组：

{ "title": "新品上架", "products": ["product-slug-1", "product-slug-2"] }

完整字段参考请参阅 references/mapping.md。

图片处理

listings[].images 中引用的图片必须以 base64 编码形式提供，并置于 images_base64 参数中，且文件名须完全一致。

准备图片步骤如下：

1. 从源平台下载商品图片
2. 对每张图片文件执行 base64 编码
3. 构建 images_base64 JSON 映射：{"filename.jpg": ""}

通过直接 API 进行批量导入

在非 MCP 环境下（例如 shell 脚本），需手动构建 ZIP 文件：

ZIP 结构

my-import/
├── listings.json          # 必需：商品数据 + 运输配置文件
├── profile.json           # 可选：店铺资料数据
├── images/                # listings.json 中引用的商品图片
│   ├── photo1.jpg
│   ├── photo2.png
│   └── ...
└── videos/                # 可选：引导视频
    └── demo.mp4

上传命令

curl -X POST "https://your-store.example.com/v1/listings/import/json" 
  -H "Authorization: Bearer " 
  -F "file=@my-import.zip"

响应示例

{
  "data": {
    "total": 10,
    "created": 8,
    "updated": 2,
    "failed": 0,
    "createdItems": [{ "slug": "product-1", "title": "Product 1" }],
    "updatedItems": [{ "slug": "product-2", "title": "Product 2" }],
    "errors": []
  }
}

参考文档

各平台详细提取指南与字段映射见 references/ 目录：

支持的数据源

方法 1：Shopify 商品导入

1. 通过 CSV 或 API 导出商品 — 具体操作请参阅 references/shopify-api.md
2. 转换为 Mobazha 格式 — 字段映射请参阅 references/mapping.md
3. 本地下载全部商品图片
4. 构建 listings.json（物理商品需包含 shippingProfiles）
5. 通过 listings_import_json MCP 工具或直接 ZIP API 上传

方法 2：Amazon 商品导入

1. 收集待导入的商品 URL 或 ASIN
2. 提取商品数据 — 抓取代码与 DOM 选择器详见 references/amazon-scrape.md
3. 转换为 Mobazha JSON 格式 — 字段映射请参阅 references/mapping.md
4. 本地下载图片（建议使用高清链接：将 _AC_US40_ 替换为 _AC_SL1500_）
5. 通过 listings_import_json MCP 工具或直接 ZIP API 上传

重要提示：请遵守 robots.txt 协议及请求频率限制；两次请求之间至少间隔 3–5 秒；导入前请确认价格准确性

方法 3：单个商品创建

对于小规模导入（少于 10 件商品），可使用 listings_create MCP 工具逐条创建商品：

{
  "listing_json": "{"slug":"my-product","metadata":{"contractType":"DIGITAL_GOOD",...},"item":{"title":"...","price":"9.99",...}}"
}

或通过 Admin API 创建：

POST /v1/listings
Content-Type: application/json
Authorization: Bearer 

图片需先通过 POST /v1/media 上传以获取内容哈希值。

认证方式

MCP 连接

若店铺已通过 MCP 连接（推荐），认证将由 MCP 会话 Token 自动完成。

直接 API 访问

对于直接 API 调用，需通过 OAuth 获取 Bearer Token，并在 Authorization 请求头中携带该 Token。

速率相关注意事项

• 批量导入在内部自动管理速率限制 — 单次 ZIP 上传即可完成全部商品导入
• 单个创建时，请依次处理并等待每条请求成功返回
• 向用户反馈进度（例如：“已创建 15/50 个商品……”）
• 较大 ZIP 文件（含 100+ 商品及图片）处理耗时约为 30–60 秒

凭证管理

• 切勿在使用后存储、记录或显示 API 密钥或密码
• Shopify/Etsy API 接入所需密钥应由用户自行提供
• MCP Token 为会话级凭证，由平台统一管理

限制条件

• 商品评论不可导入（因其为店铺专属数据）
• 物理商品必须配置运输配置文件 — 请在导入 JSON 中一并提供
• 支付选项在店铺层级设置，不支持按商品单独配置
• 数字商品文件需重新上传至 Mobazha
• ZIP 文件最大体积：300 MB（可配置）
• 单个商品所附视频最大体积：15 MB