妙手ERP-产品认领

概述

妙手ERP产品认领

将公共采集箱中的商品认领到平台采集箱。这是一个写操作，会创建或映射平台专属采集箱记录。

典型用户请求

• "把商品 12345 认领到 TikTok"
• "把 12345,12346 从公共采集箱转到 Ozon 采集箱"
• "这几个公共采集箱商品认领到 Temu 半托管"
• "采集完这些货源后认领到 Shopee"
• "认领到 Shopee Global，后面走全球商品发布"
• "认领到美客多 / MercadoLibre，后面补类目属性再发布"
• "认领完成后给我返回平台采集箱 ID"
• "这些商品先认领到平台，后面再编辑类目属性"

适用范围

此技能仅用于跨采集箱转移：

• 从公共采集箱明细 ID 转移到平台采集箱明细 ID。
• 在平台专属编辑和发布之前执行。
• 在公共采集箱数据已检查或编辑之后执行。

不适用于以下操作：

• 采集货源链接到公共采集箱。
• 编辑标题、价格、库存、图片、SKU、类目或属性。
• 将商品发布到店铺。
• 在用户未指定目标平台时代为决定平台。

安全分级

认领属于写操作。它会改变 ERP 工作流状态，并可能创建平台专属采集箱记录。在调用认领接口前，务必进行预览并要求用户明确确认。

不要将认领和发布合并在一次确认中。它们是独立的写操作。

必需输入

serialNumber 是内部 API 兼容字段，不应向普通业务用户索要。除非连接器、开发者文档或当前 API 文档明确提供了其他值，否则始终使用 serialNumber=1。

平台代码

当前认领 API 文档支持以下平台：

旧版平台代码如 lazada、amazon、shein 可能存在于已安装的旧版技能或历史工作流中，但不在当前认领 API 文档中。使用旧版平台代码前请先确认。

在脚本中归一化用户别名，但在最终请求载荷中保持 API 代码的原始大小写格式。

API 鉴权

调用妙手ERP开放平台 API 前，请确保用户已授权通过审核的开放平台应用。

1. 从本地 resources/config.json、环境变量 MIAOSHOU_APP_KEY 和 MIAOSHOU_APP_SECRET，或安全主机连接器中加载凭证。
2. 可选：设置 MIAOSHOU_BASE_URL；默认为 https://openapi-erp.91miaoshou.com。
3. 若账号已开启 IP 白名单，确认调用方主机 IP 已在白名单中。
4. 发送带签名的 POST 请求，包含 Content-Type: application/json、x-app-key、x-timestamp 和 x-sign 请求头。

签名规则：

sign = HmacSHA256(appSecret, appSecret + path + timestamp + appKey + bodyJson + appSecret)

使用精确的 API 路径，而非完整 URL。使用秒级 Unix 时间戳。使用请求体中实际发送的紧凑 JSON 字符串。切勿打印 AppSecret、签名请求头或包含凭证的请求数据。

常见鉴权错误：

标准工作流

1. 解析公共采集箱 detailIds 和目标 platform。
2. 若缺少商品 ID，向用户询问。若缺少平台，向用户询问目标平台。
3. 不要询问 serialNumber；使用内部默认值 1。
4. 条件允许时，查询每个公共采集箱 ID 的商品详情。
5. 展示商品预览，包含 ID、标题、价格/SKU 数量/图片数量（如可获取）。
6. 展示认领计划，包含商品数量、公共采集箱 ID、目标平台、迁移行为以及明确的不执行项。
7. 仅在用户明确确认后调用认领接口。
8. 分别报告成功、失败和部分成功的结果。
9. 保留公共采集箱 ID 到平台采集箱 ID 的映射，供后续平台编辑/发布工作流使用。
10. 仅对成功认领的商品，引导用户使用对应的平台专属技能。

确认模板

请确认认领计划：
- 商品数量：N
- 公共采集箱商品ID：12345, 12346
- 目标平台：tiktok / tiktokGlobal / ozon / pddkj / pddkjChoice / shopee / shopeeGlobal / mercadolibre
- 将迁移：标题、图片、SKU、价格、库存、基础属性
- 不会执行：平台采集箱编辑、类目属性补全、发布

确认后才会调用认领接口。请回复"确认认领"或"取消"。

场景处理

API 摘要

• 接口地址：POST /open/v1/product/common_collect_box/common_collect_box/claimed
• 请求字段：detailSerialNumberPlatformList
• 列表项字段：detailId、platform、serialNumber
• 默认 serialNumber：1
• 响应字段：platformCollectBoxDetailIdMap

请求示例：

{
  "detailSerialNumberPlatformList": [
    {
      "detailId": 12345,
      "platform": "ozon",
      "serialNumber": 1
    }
  ]
}

响应映射示例：

{
  "platformCollectBoxDetailIdMap": {
    "ozon": {
      "12345": 67890
    }
  }
}

在实现替代调用方式或调试接口行为前，请先加载 references/api_reference.md。

CLI 命令行工具

python {base_dir}/scripts/claim_to_platform.py platforms
python {base_dir}/scripts/claim_to_platform.py detail --detail-id 12345
python {base_dir}/scripts/claim_to_platform.py claim --detail-ids 12345,12346 --platform ozon
python {base_dir}/scripts/claim_to_platform.py claim --detail-ids 12345 --platform pddkjChoice
python {base_dir}/scripts/claim_to_platform.py claim --detail-ids 12345 --platform shopee
python {base_dir}/scripts/claim_to_platform.py claim --detail-ids 12345 --platform shopeeGlobal
python {base_dir}/scripts/claim_to_platform.py batch-claim --file claim_list.json

失败处理

对于部分失败的情况，分别展示成功映射和失败的 ID。未经用户指示，不要自动重试失败的写操作。

相关技能

配置

使用 resources/config.json.example 作为本地配置模板。不要分发真实的 resources/config.json。

脚本使用说明

• 脚本名称：claim_to_platform.py
• 使用 --platform 参数，而非 --targetPlatform。
• 使用 --detail-ids 传入公共采集箱明细 ID，而非店铺 ID。
• CLI 参数使用 kebab-case 命名风格，如 --detail-ids。
• 正常使用时省略 --serial-number；脚本默认值为 1。