慧企星助 开放平台文档

慧企星助 开放平台面向企业三方系统提供标准 HTTP API，支持员工、绑定关系、项目、目标与目标复盘、任务、通知、便签、标签、贡献点和附件上传能力。 所有接口默认只作用于当前 API Key 所属企业，权限由后端统一控制并在请求时强校验。

显示全部接口

福利接口

福利接口查询需要 welfare.read 权限，申请、审核、评论与设置维护需要 welfare.write 权限，依赖企业套餐福利模块。商品与分类为企业维度数据，申请记录、待审核申请与金币记录只返回当前操作人可见范围内的数据。

必填请求头：本模块全部接口（含查询）都必须提供 X-Employee-Virtual-Id，未传或不属于当前企业时返回 403，错误信息为“请通过 X-Employee-Virtual-Id 指定当前操作人”。
异步说明：申请福利与审核福利走异步队列处理，接口返回成功只表示请求已受理，最终是否通过以申请记录的状态为准；福利设置与商品评论为同步生效。
GET /api/openplatform/welfare/categories

查询当前企业的福利商品分类列表。

{
  "statusCode": 100,
  "msg": "获取成功",
  "data": [
    {
      "id": "8f3b52e4-1c2d-4a5b-9e6f-7a8b9c0d1e2f",
      "name": "办公好物"
    }
  ]
}
字段类型说明
idguid分类 Id，用于商品列表与记录筛选的 categoryId。
namestring分类名称。
GET /api/openplatform/welfare/goods

分页查询福利商品列表。

参数类型必填说明
pageint否页码，默认 1。
pageSizeint否每页条数，默认 20，最大 100。
categoryIdguid否福利分类 Id，不传查询全部分类。
keywordstring否按商品名称模糊搜索；不传返回全部。
sortstring否排序方式，字符串枚举：score 按贡献点价格、time 按创建时间，默认 score。传其它值返回 400，错误信息为“sort 必须为 score 或 time”。
 
{
  "statusCode": 100,
  "msg": "获取成功",
  "data": {
    "total": 12,
    "page": 1,
    "pageSize": 20,
    "items": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "定制保温杯",
        "img": "https://cdn.example.com/welfare/20260901/cup.png",
        "peopleNumber": 8,
        "timesNumber": 15,
        "price": 50,
        "createdAt": "2026-09-01T10:00:00+08:00",
        "countLimit": {
          "enable": true,
          "name": "每月",
          "limit": 2,
          "current": 1
        },
        "requireInfo": {
          "enable": true,
          "msg": "贡献点不足（30/50）"
        }
      }
    ]
  }
}

列表响应字段

字段类型说明
data.totallong符合筛选条件的商品总数。
data.pageint当前页码，从 1 开始。
data.pageSizeint当前页返回条数上限，范围为 1 到 100。
data.itemsWelfareGoods[]当前页商品列表。

WelfareGoods 字段

字段类型说明
idguid商品 Id，用于详情、兑换要求、评论与申请。
namestring商品名称。
imgstring商品图片地址。
pricedecimal兑换价格，单位金币。
peopleNumberint累计领取人数。
timesNumberint累计领取次数。
createdAtstring上架时间，ISO 8601 带时区。
countLimitobject当前已生效的周期性名额限制：enable 是否受限、name 周期标题（每日/每周/每月/每季度/每年）、limit 为周期内上限、current 为当前已用次数；不返回未生效的周期。
requireInfoobject兑换要求校验结果：enable 是否存在未达标要求、msg 未达标原因文案（全部达标时为空字符串）。
GET /api/openplatform/welfare/goods/{id}

查询福利商品详情，包含商品介绍与完整兑换要求。商品不存在或不属于当前企业时返回 400，错误信息为“福利不存在！”。

{
  "statusCode": 100,
  "msg": "获取成功",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "定制保温杯",
    "img": "https://cdn.example.com/welfare/20260901/cup.png",
    "price": 50,
    "remark": "不锈钢内胆，容量 500ml",
    "createdAt": "2026-09-01T10:00:00+08:00",
    "enableApply": false,
    "timesNumber": 15,
    "peopleNumber": 8,
    "requireInfo": {
      "dayLimit": { "enable": false, "name": "每日", "limit": 0, "current": 0 },
      "weekLimit": { "enable": false, "name": "每周", "limit": 0, "current": 0 },
      "monthLimit": { "enable": true, "name": "每月", "limit": 2, "current": 1 },
      "quarterLimit": { "enable": false, "name": "每季度", "limit": 0, "current": 0 },
      "yearLimit": { "enable": false, "name": "每年", "limit": 0, "current": 0 },
      "score": { "enable": true, "name": "贡献点", "limit": 50, "current": 30 },
      "requireMedalList": [],
      "requireAchievementList": [],
      "requireTitleList": []
    }
  }
}

详情响应字段

字段类型说明
id / name / img / price / createdAt—与商品列表口径一致。
remarkstring商品介绍；未填写时为空字符串。
enableApplybool当前操作人是否已满足全部兑换要求，可直接申请。
timesNumber / peopleNumberint累计领取次数与领取人数。
requireInfoobject完整兑换要求，见下方字段说明。

requireInfo 字段

字段类型说明
dayLimit / weekLimit / monthLimit / quarterLimit / yearLimitobject各周期的领取名额限制：enable 是否启用、name 周期标题、limit 为周期内上限、current 为当前已用次数。
scoreobject贡献点要求：limit 为要求点数、current 为当前操作人现有贡献点。
requireMedalListarray奖章要求，每项含 id、name、img、count（所需获得次数）、complete（是否已达标）；无要求时为空数组。
requireAchievementListarray成就要求，每项含 id、name、level（所需等级）、img、complete；无要求时为空数组。
requireTitleListarray成长路线要求，每项含 libraryId、id、name、library；无要求时为空数组。
兑换校验：申请前建议先读取本接口的 enableApply；为 false 时提交申请会被源站拒绝，并返回具体的未达标原因。
GET /api/openplatform/welfare/goods/{id}/requirement

单独查询福利商品的兑换要求与当前操作人的达标情况，返回结构与商品详情的 requireInfo 完全一致。

{
  "statusCode": 100,
  "msg": "获取成功",
  "data": {
    "dayLimit": { "enable": false, "name": "每日", "limit": 0, "current": 0 },
    "monthLimit": { "enable": true, "name": "每月", "limit": 2, "current": 1 },
    "score": { "enable": true, "name": "贡献点", "limit": 50, "current": 30 },
    "requireMedalList": [],
    "requireAchievementList": [],
    "requireTitleList": []
  }
}
字段说明：各周期限制独立返回，enable 为 true 表示该周期名额已用满；未启用对应周期时，该字段的 enable 为 false、数量为 0。
GET /api/openplatform/welfare/goods/{id}/comments

查询福利商品的评论列表。

{
  "statusCode": 100,
  "msg": "获取成功",
  "data": [
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "employeeVirtualId": "emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz",
      "name": "张三",
      "headImg": "https://cdn.example.com/head/20260914/zhangsan.png",
      "content": "很实用",
      "createdAt": "2026-09-14T09:05:00+08:00"
    }
  ]
}
字段类型说明
idguid评论 Id。
employeeVirtualIdstring评论人 virtualId。
namestring评论人姓名。
headImgstring评论人头像地址；未上传时为空字符串。
contentstring评论内容。
createdAtstring评论时间，ISO 8601 带时区。
POST /api/openplatform/welfare/goods/{id}/comments

发表福利商品评论，同步生效。

参数类型必填说明
contentstring是评论内容；为空时返回 400，错误信息为“评论内容不能为空”。
 
{
  "content": "很实用"
}
GET /api/openplatform/welfare/records

分页查询当前操作人本人的福利申请记录。

参数类型必填说明
pageint否页码，默认 1。
pageSizeint否每页条数，默认 20，最大 100。
categoryIdguid否福利分类 Id，不传查询全部分类。
sortstring否排序方式，字符串枚举：time 按申请时间、price 按贡献点，默认 time。传其它值返回 400，错误信息为“sort 必须为 time 或 price”。
 
{
  "statusCode": 100,
  "msg": "获取成功",
  "data": {
    "total": 3,
    "page": 1,
    "pageSize": 20,
    "items": [
      {
        "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
        "name": "定制保温杯",
        "img": "https://cdn.example.com/welfare/20260901/cup.png",
        "remark": "不锈钢内胆，容量 500ml",
        "reason": "本月积分兑换",
        "price": 50,
        "orderNum": "WL20260914001",
        "createdAt": "2026-09-14T09:05:00+08:00",
        "status": 0,
        "statusStr": "待审批"
      }
    ]
  }
}

WelfareRecord 字段

字段类型说明
idguid申请记录 Id，用于详情与审核路径。
name / img / remarkstring福利名称、图片与描述。
reasonstring申请事由。
pricedecimal兑换价格，单位金币。
orderNumstring兑换单号。
createdAtstring申请时间，ISO 8601 带时区。
statusint申请状态：0 待审批、1 已完成、-1 不通过。
statusStrstring状态中文文案，与 status 配套返回。
requireDataobject申请时快照的兑换要求（各周期名额、贡献点、奖章、成就、成长路线要求）；无要求时各字段为 0 或空数组。
GET /api/openplatform/welfare/records/{id}

查询福利申请记录详情，包含申请人、审批人、审批时间与操作轨迹。记录不存在时返回 400，错误信息为“申请信息不存在！”。

{
  "statusCode": 100,
  "msg": "获取成功",
  "data": {
    "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "name": "定制保温杯",
    "price": 50,
    "reason": "本月积分兑换",
    "orderNum": "WL20260914001",
    "createdAt": "2026-09-14T09:05:00+08:00",
    "status": 1,
    "statusStr": "已完成",
    "applyUser": {
      "virtualId": "emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz",
      "name": "张三",
      "headImg": "https://cdn.example.com/head/20260914/zhangsan.png"
    },
    "checker": {
      "virtualId": "emp_Q8eR3nZl9sMq5dO2tWy4cI0xBf7gKvLa",
      "name": "李四",
      "headImg": "https://cdn.example.com/head/20260914/lisi.png"
    },
    "checkedAt": "2026-09-14T18:20:00+08:00",
    "operateList": [
      {
        "time": "2026-09-14T09:05:00+08:00",
        "remark": "提交申请",
        "content": "提交了福利兑换申请"
      }
    ]
  }
}

详情响应字段

详情返回包含上述 WelfareRecord 的全部字段，并额外包含以下字段。

字段类型说明
applyUserobject申请人，含 virtualId、name、headImg。
checkerobject实际审批人，字段口径同 applyUser；未审批时为空对象。
checkersobject[]审批人列表，每项含 virtualId、name、掩码 phone 与 headImg；未设置审批人时为空数组。
checkedAtstring审批时间，ISO 8601 带时区；未审批时为默认值。
operateListarray操作轨迹，每项含 time（操作时间）、remark（操作类型文案）与 content（操作详细内容）。
GET /api/openplatform/welfare/pendingRecords

分页查询待当前操作人审核的福利申请，只返回状态为待审批且审批人包含当前操作人的记录。

参数类型必填说明
pageint否页码，默认 1。
pageSizeint否每页条数，默认 20，最大 100。
categoryIdguid否福利分类 Id，不传查询全部分类。
sortstring否排序方式：time 按申请时间、price 按贡献点，默认 time；非法值返回 400，错误信息为“sort 必须为 time 或 price”。
 
{
  "statusCode": 100,
  "msg": "获取成功",
  "data": {
    "total": 2,
    "page": 1,
    "pageSize": 20,
    "items": [
      {
        "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
        "name": "定制保温杯",
        "price": 50,
        "reason": "本月积分兑换",
        "orderNum": "WL20260914001",
        "createdAt": "2026-09-14T09:05:00+08:00",
        "status": 0,
        "statusStr": "待审批",
        "applyUser": {
          "virtualId": "emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz",
          "name": "张三",
          "headImg": "https://cdn.example.com/head/20260914/zhangsan.png"
        },
        "checkerVirtualIds": [
          "emp_Q8eR3nZl9sMq5dO2tWy4cI0xBf7gKvLa"
        ]
      }
    ]
  }
}

待审核记录字段

字段类型说明
applyUserobject申请人，含 virtualId、name、headImg。
checkersobject[]该申请的审批人成员对象数组（每项含 virtualId、name 与掩码 phone），与员工接口返回的成员对象（含 virtualId、name 与掩码 phone）同一口径。
字段说明：待审核记录在 WelfareRecord 基础上额外返回 applyUser（申请人）与 checkers（审批人成员对象），审核时把 id 传入审核接口即可。
GET /api/openplatform/welfare/goldCoinScales

查询贡献点兑换金币的比例列表，按比例、类型升序。

{
  "statusCode": 100,
  "msg": "获取成功",
  "data": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "type": 4,
      "name": "特别表彰 / 客户好评",
      "fullTitle": "特别表彰 / 客户好评",
      "scale": 10
    }
  ]
}
字段类型说明
idstring关联贡献项 Id。
typeint关联类型：1 任务贡献、2 汇报贡献、3 基础贡献、4 全部行为标准。
name / fullTitlestring贡献项标题，多级贡献项以“ / ”拼接全路径。
scaledecimal兑换比例：1 点贡献可兑换多少金币。
GET /api/openplatform/welfare/goldCoinRecords

分页查询当前操作人的金币流水记录。

参数类型必填说明
pageint否页码，默认 1。
pageSizeint否每页条数，默认 20，最大 100。
 
{
  "statusCode": 100,
  "msg": "获取成功",
  "data": {
    "total": 5,
    "page": 1,
    "pageSize": 20,
    "items": [
      {
        "id": "d4e5f6a7-b8c9-0123-defa-456789012345",
        "createdAt": "2026-09-14T18:20:00+08:00",
        "money": -50,
        "remark": "兑换定制保温杯",
        "useType": -1
      }
    ]
  }
}
字段类型说明
idguid流水 Id。
createdAtstring流水时间，ISO 8601 带时区。
moneydecimal金币变动数量，支出为负数、收入为正数。
remarkstring流水说明。
useTypeint流水类型：0 贡献转换、-1 兑换福利商品、1 审核不通过退回。
GET /api/openplatform/welfare/config

查询当前企业的福利配置与当前操作人的福利权限，可用于判断能否审核申请、能否维护金币兑换比例。

{
  "statusCode": 100,
  "msg": "获取成功",
  "data": {
    "myGoldCoin": 260,
    "barrageImg": "https://cdn.example.com/welfare/barrage.png",
    "permission": {
      "audit": true,
      "goldCoinSettings": false
    }
  }
}
字段类型说明
myGoldCoindecimal当前操作人的金币余额。
barrageImgstring福利弹幕背景图地址；未配置时为空字符串。
permission.auditbool是否有福利审核权限，同时决定能否维护弹幕图片。
permission.goldCoinSettingsbool是否有金币兑换比例设置权限。
POST /api/openplatform/welfare/apply

申请兑换福利商品，走异步队列处理。申请人固定为当前操作人，不支持代他人申请。

参数类型必填说明
goodsIdguid是福利商品 Id；为空时返回 400，错误信息为“福利商品标识不能为空”。
reasonstring否申请事由，会展示给审批人。
 
{
  "goodsId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "reason": "本月积分兑换"
}
受理说明：本接口返回成功只代表申请已进入队列，兑换要求校验、金币扣减与审批结果都在异步处理完成后生效；未通过时会在申请记录中给出原因，可用 GET /welfare/records 查询结果。常见失败原因包括金币不足、贡献点不足、名额已用完、未配置审批人等。
POST /api/openplatform/welfare/records/{id}/actions/pass

审核通过福利申请，走异步队列处理。只能审核审批人包含当前操作人且状态为待审批的记录，重复审核会被源站拒绝。

参数类型必填说明
reasonstring否审批意见。
attachmentUrlsstring[]否附件地址列表，须为平台已上传的附件地址。
 
{
  "reason": "同意兑换",
  "attachmentUrls": []
}
POST /api/openplatform/welfare/records/{id}/actions/noPass

审核不通过福利申请，走异步队列处理，已扣除的金币会退回申请人。

参数类型必填说明
reasonstring否不通过原因，建议填写以便申请人查看。
attachmentUrlsstring[]否附件地址列表，须为平台已上传的附件地址。
 
{
  "reason": "本月名额已用完，请下月再申请",
  "attachmentUrls": []
}
调用约束：审核通过与不通过都会改变他人已提交申请的结果，调用前必须把商品名称、申请人与事由展示给用户并取得明确确认。
PUT /api/openplatform/welfare/settings

维护企业福利设置，同步生效。设置项与所需权限一一对应，无对应权限时源站返回“抱歉，您没有权限设置!”。

参数类型必填说明
settingstring是设置项，字符串枚举：barrageImage 弹幕图片地址（需要审核权限）、goldCoinScale 贡献点兑换金币比例（需要金币设置权限）。为空时返回 400，错误信息为“福利设置项不能为空”；传其它值返回 400，错误信息为“setting 必须为 barrageImage 或 goldCoinScale”。
valuestring是设置值：barrageImage 传图片地址，goldCoinScale 传比例数字字符串。
 
{
  "setting": "goldCoinScale",
  "value": "10"
}
MCP 工具 welfare_query

福利查询工具，需要 welfare.read 权限，覆盖上述全部 GET 查询能力。queryType 取值：goodsList 商品列表（分页）、goodsDetail 商品详情、goodsRequire 兑换要求、goodsComments 商品评论、categoryList 分类、myRecords 我的申请记录（分页）、recordDetail 申请详情、pendingList 待我审核（分页）、goldCoinScales 兑换比例、goldCoinRecords 金币记录（分页）、config 企业配置。

{
  "queryType": "goodsList",
  "goodsSort": "score",
  "page": 1,
  "pageSize": 20
}
参数映射：goodsId 对应 REST 的商品 id、recordId 对应申请记录 id；商品排序用 goodsSort、记录排序用 recordSort，取值与 REST 一致（非法值分别提示“goodsSort 必须为 score 或 time”“recordSort 必须为 time 或 price”）。
MCP 工具 welfare_action

福利写操作工具，需要 welfare.write 权限。action 取值：apply 申请福利、pass 审核通过、noPass 审核不通过、comment 评论商品、settings 维护福利设置。

{
  "action": "apply",
  "goodsId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "reason": "本月积分兑换"
}
调用约束：申请与审核会改变他人或自己的福利权益，调用前必须把商品名称、数量与事由完整展示给用户并取得明确确认；申请与审核为异步处理，返回成功仅代表已受理。
© 2026 郑州星云互联 开放平台