# 钉钉素材库接口对接文档

## 1. 对接目标

钉钉流程填写以下 5 个字段后，调用素材库接口判断是否有符合条件的素材：

- 需求类型
- 品牌
- 场景类别
- 产品类别
- SPU

返回规则：

- 如果有符合素材，返回一个可用地址
- 如果没有符合素材，返回：`该SPU下暂无素材`

---

## 2. 字段对应关系

钉钉字段和素材库字段对应如下：

- `需求类型` = `materialType`（素材类型）
- `品牌` = `categoryName`（店铺）
- `场景类别` = `sceneName`
- `产品类别` = `productCategoryName`
- `SPU` = `productModel`

注意：

- “品牌”在本项目里实际对应的是“店铺”
- “需求类型”实际对应的是“素材类型”

---

## 3. 鉴权方式

结论：钉钉用户提交表单时，不需要、也不应该手动输入请求头。

建议钉钉负责人把密钥固定配置在接口地址里，用户只填写业务字段。

本次改动后，钉钉这两个接口同时支持两种鉴权方式：

- 推荐给钉钉低代码流程：固定 URL 参数 `apiKey`
- 推荐给程序系统对接：固定请求头 `X-API-Key`

两种方式任选一种即可，不需要同时配置。

钉钉流程推荐使用：

```http
apiKey=5073534d7a59babbc45397a8eac5943b
```

也就是把 `apiKey` 作为固定 URL 参数放到接口地址中。

系统对系统调用仍然支持请求头方式：

```http
X-API-Key: 5073534d7a59babbc45397a8eac5943b
```

说明：

- 当前生产可用 Key 名称：`AI生图系统`
- 当前生产可用 Key：`5073534d7a59babbc45397a8eac5943b`
- 钉钉低代码流程如果不方便固定请求头，就使用 URL 参数 `apiKey`
- `apiKey` 由钉钉流程管理员固定配置，不暴露给普通填表用户

钉钉负责人配置时要注意：

- `apiKey` 是固定参数，不要做成表单字段
- 普通用户只需要填写或选择：需求类型、品牌、场景类别、产品类别、SPU
- 如果钉钉侧有“连接器公共请求头”或“固定请求头”配置，也可以把 `X-API-Key` 配在那里
- 如果没有固定请求头能力，就直接使用本文档里的 `?apiKey=...` 地址

---

## 4. 接口 1：获取下拉选项

### 4.1 用途

给钉钉流程生成下拉选项，避免手填出错。

### 4.2 请求信息

钉钉推荐配置地址：

```http
GET https://sc.jiansun.vip/api/external/dingtalk-material-options?apiKey=5073534d7a59babbc45397a8eac5943b
```

不需要用户手填请求头。

如果钉钉侧可以配置固定请求头，也可以继续用：

```http
X-API-Key: 5073534d7a59babbc45397a8eac5943b
```

### 4.3 返回示例

```json
{
  "success": true,
  "data": {
    "requirementTypes": ["任务-详情", "任务-页面", "任务-3D原图"],
    "brands": ["顾家家居", "林氏木业"],
    "sceneCategories": ["客厅", "卧室"],
    "productCategories": ["沙发", "床"]
  }
}
```

### 4.4 字段说明

- `requirementTypes`：需求类型下拉
- `brands`：品牌下拉，实际就是店铺
- `sceneCategories`：场景类别下拉
- `productCategories`：产品类别下拉

### 4.5 接入建议

钉钉流程应先调用这个接口，把以下字段做成下拉：

- 需求类型
- 品牌
- 场景类别
- 产品类别

不建议手填。

---

## 5. 接口 2：查询是否有素材

### 5.1 用途

用户选择完 5 个字段后，调用这个接口判断有没有素材。

### 5.2 请求信息

钉钉推荐配置地址：

```http
GET https://sc.jiansun.vip/api/external/dingtalk-material-match?apiKey=5073534d7a59babbc45397a8eac5943b
```

不需要用户手填请求头。

如果钉钉侧可以配置固定请求头，也可以继续用：

```http
X-API-Key: 5073534d7a59babbc45397a8eac5943b
```

请求参数：

- `apiKey`：固定鉴权密钥，由钉钉负责人固定配置，不给普通用户填写
- `requirementType`：需求类型
- `brand`：品牌（实际是店铺）
- `sceneCategory`：场景类别
- `productCategory`：产品类别
- `spu`：SPU

### 5.3 请求示例

```http
GET https://sc.jiansun.vip/api/external/dingtalk-material-match?apiKey=5073534d7a59babbc45397a8eac5943b&requirementType=任务-详情&brand=顾家家居&sceneCategory=客厅&productCategory=沙发&spu=SPU001
```

---

## 6. 查询接口返回示例

### 6.1 命中素材时

```json
{
  "success": true,
  "data": {
    "matched": true,
    "message": "查询成功",
    "spu": "SPU001",
    "requirementType": "任务-详情",
    "brand": "顾家家居",
    "sceneCategory": "客厅",
    "productCategory": "沙发",
    "address": "https://sc.jiansun.vip/uploads/previews/spu001.jpg",
    "materialId": "material-1",
    "updatedAt": "2026-04-30T08:00:00.000Z"
  }
}
```

钉钉侧重点关注：

- `matched = true`
- `address` 有值

### 6.2 未命中素材时

```json
{
  "success": true,
  "data": {
    "matched": false,
    "message": "该SPU下暂无素材",
    "spu": "SPU001",
    "requirementType": "任务-详情",
    "brand": "顾家家居",
    "sceneCategory": "客厅",
    "productCategory": "沙发",
    "address": null
  }
}
```

钉钉侧重点关注：

- `matched = false`
- `message = 该SPU下暂无素材`

---

## 7. 推荐接入顺序

推荐按以下顺序接入：

1. 先调用“下拉选项接口”
2. 用返回结果生成钉钉表单下拉
3. 用户选择完 5 个字段后
4. 再调用“素材匹配接口”
5. 根据 `matched` 和 `address` 做后续流程判断

---

## 8. 注意事项

- `SPU` 为必填
- 其余字段建议全部走下拉，不要手输
- “品牌”不是独立品牌库字段，实际对应店铺
- “需求类型”不是自由文本，实际对应素材类型
- 如果接口返回 `INVALID_API_KEY`，说明 `apiKey` 参数或 `X-API-Key` 请求头没有正确配置
- 普通填表用户不应看到 `apiKey` 字段；它应由钉钉流程管理员固定在接口地址或连接器配置里

---

## 9. 生产环境信息

- 生产域名：`https://sc.jiansun.vip`
- 下拉选项接口：`/api/external/dingtalk-material-options`
- 素材匹配接口：`/api/external/dingtalk-material-match`