WuYongJie/gongxiangp2

Fork 0

chenpei 8c39d96249 chore: sync latest project source

2026-05-07 16:37:22 +08:00

6.0 KiB

Raw Blame History

钉钉素材库接口对接文档

1. 对接目标

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

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

返回规则：

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

2. 字段对应关系

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

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

注意：

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

3. 鉴权方式

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

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

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

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

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

钉钉流程推荐使用：

apiKey=5073534d7a59babbc45397a8eac5943b

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

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

X-API-Key: 5073534d7a59babbc45397a8eac5943b

说明：

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

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

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

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

4.1 用途

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

4.2 请求信息

钉钉推荐配置地址：

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

不需要用户手填请求头。

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

X-API-Key: 5073534d7a59babbc45397a8eac5943b

4.3 返回示例

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

4.4 字段说明

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

4.5 接入建议

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

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

不建议手填。

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

5.1 用途

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

5.2 请求信息

钉钉推荐配置地址：

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

不需要用户手填请求头。

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

X-API-Key: 5073534d7a59babbc45397a8eac5943b

请求参数：

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

5.3 请求示例

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

6. 查询接口返回示例

6.1 命中素材时

{
  "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 未命中素材时

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