152 lines
4.1 KiB
Markdown
152 lines
4.1 KiB
Markdown
# 产品平台条码图片推送接口
|
||
|
||
更新时间：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` | 反查接口地址，可用来拉该条码全部历史记录 |
|
||
|
||
## 通知示例
|
||
|
||
```json
|
||
{
|
||
"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"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## 反查接口
|
||
|
||
产品平台如果要主动按条码拉历史图片，调用：
|
||
|
||
```http
|
||
GET /api/external/product-barcode-images?barcode={barcode}
|
||
```
|
||
|
||
请求头：
|
||
|
||
```http
|
||
X-API-Key: your-api-key
|
||
```
|
||
|
||
## 成功判定
|
||
|
||
- 回调返回 `2xx`：视为成功
|
||
- 回调超时、网络失败、非 `2xx`：视为失败
|
||
|
||
## 重试与补发
|
||
|
||
- 通知发送是异步执行，不阻塞素材入库成功
|
||
- 失败后会自动重试
|
||
- 超过重试上限后，会进入待人工处理
|
||
- 素材库后台支持手工补发
|
||
|
||
## 对接建议
|
||
|
||
- 产品平台接到通知后，建议按 `eventId + barcode` 做幂等去重
|
||
- 需要最新图片时，优先使用 `isLatest = true` 的记录
|
||
- 需要完整历史时，直接调用 `lookupUrl`
|
||
- 如果回调接口会做验签或 Header 校验，请在素材库后台配置对应鉴权方式
|