gongxiangp2/docs/产品平台条码图片推送接口.md

产品平台条码图片推送接口

更新时间：2026-04-22

目标

这组对接能力用于让素材库在出现新的「带产品条码的 SKU 预览图」时，主动通知产品平台。

产品平台收到通知后可以：

1. 直接使用通知里的预览图地址做图片处理
2. 按 lookupUrl 反查同一个产品条码的全部历史图片
3. 根据 isLatest 判断当前最新生效图片

触发规则

• 仅对 任务-详情 生效
• 当一次保存里出现“带产品条码的 SKU 预览图新增或更新”时触发
• 同一批次只发 1 次通知
• 只推送本次变更的条码图片，不回推历史全量
• 当前不发送“条码解绑/删除”通知

主识别键

• 主键：barcode
• 辅助字段：materialId、assetId

说明：

• 同一个 barcode 可能命中多条历史图片
• “当前有效”按最新上传时间判断
• 产品平台不要把 skuCode 当成唯一键

通知方式

• 方法：POST
• 方向：素材库服务端主动调用产品平台提供的回调地址
• Content-Type：application/json

回调地址、鉴权方式、是否启用，由素材库后台配置。

当前支持的回调鉴权方式：

• 无鉴权
• Bearer Token
• 自定义 Header

通知事件

• eventType: task-detail.barcode-images.updated

通知 payload

顶层字段

字段	说明
eventId	事件唯一 ID
eventType	固定为 task-detail.barcode-images.updated
materialId	素材记录 ID
materialType	当前固定为 任务-详情
taskNo	任务号，可为空
productModel	SPU
categoryName	店铺
shopName	店铺，当前与 categoryName 相同
sceneName	场景
occurredAt	本次推送时间
items	条码图片清单，按“一条码一记录”展开

items[] 字段

字段	说明
materialId	素材记录 ID
assetId	SKU 预览图资产 ID
skuCode	SKU 编号
barcode	产品条码
previewUrl	SKU 预览图地址
fileName	预览图文件名
sortOrder	预览图顺序
uploadedAt	该张 SKU 预览图上传时间
updatedAt	最近更新时间
uploaderName	上传人
isLatest	该条码当前最新生效的图片
lookupUrl	反查接口地址，可用来拉该条码全部历史记录

通知示例

{
  "eventId": "evt-20260422-0001",
  "eventType": "task-detail.barcode-images.updated",
  "materialId": "35d8644b-1e09-4ce8-9bb0-c529b39ba52e",
  "materialType": "任务-详情",
  "taskNo": "TASK202604220001",
  "productModel": "XG025503",
  "categoryName": "旗舰店",
  "shopName": "旗舰店",
  "sceneName": "客厅",
  "occurredAt": "2026-04-22T09:10:00.000Z",
  "items": [
    {
      "materialId": "35d8644b-1e09-4ce8-9bb0-c529b39ba52e",
      "assetId": "asset-sku-1",
      "skuCode": "SKU-001",
      "barcode": "690000000001",
      "previewUrl": "https://s3.jiansun.vip/gongxiangpan/public-display/task-detail/material-1/sku/1.webp",
      "fileName": "sku-1.webp",
      "sortOrder": 0,
      "uploadedAt": "2026-04-22T09:00:00.000Z",
      "updatedAt": "2026-04-22T09:05:00.000Z",
      "uploaderName": "张三",
      "isLatest": true,
      "lookupUrl": "https://sc.jiansun.vip/api/external/product-barcode-images?barcode=690000000001"
    }
  ]
}

反查接口

产品平台如果要主动按条码拉历史图片，调用：

GET /api/external/product-barcode-images?barcode={barcode}

请求头：

X-API-Key: your-api-key

成功判定

• 回调返回 2xx：视为成功
• 回调超时、网络失败、非 2xx：视为失败

重试与补发

• 通知发送是异步执行，不阻塞素材入库成功
• 失败后会自动重试
• 超过重试上限后，会进入待人工处理
• 素材库后台支持手工补发

对接建议

• 产品平台接到通知后，建议按 eventId + barcode 做幂等去重
• 需要最新图片时，优先使用 isLatest = true 的记录
• 需要完整历史时，直接调用 lookupUrl
• 如果回调接口会做验签或 Header 校验，请在素材库后台配置对应鉴权方式