[泛微 Ecology9] 丸子喂饭篇: restful 新建流程接口详解(/api/workflow/paService/doCreateRequest)

本文摘要

泛微E9中用于自动新建流程实例的 REST 接口 doCreateRequest，文章从请求头鉴权、请求方式与编码格式，到主表与明细表数据组装、返回值判断和常见报错排查做了完整拆解。适合做系统集成、数据迁移或定时发起流程的开发者参考，重点在于字段名必须与数据库字段名一致，并注意请求格式与用户创建权限，否则容易报参数或权限错误。

📌

该文章由丸子引导 AI 辅助制作生成，如有改进意见，欢迎评论区留言。

引言

这个接口可以说是泛微 E9 里用得最多的 REST 接口之一了——新建流程实例。

不管是做系统集成、数据迁移、还是定时任务自动发起流程，都绕不开它。但官方文档嘛……懂的都懂，参数一堆，示例不够，踩坑不少。

今天丸子就把这个接口掰开了揉碎了讲一遍，争取让你看完就能用。

一眼看明白：直接上 curl

😄 如果你对泛微接口已经有一定了解，直接看这段就够了。当然，下面有详细解释，需要的话可以继续往下翻~。

curl -X POST 'https://your-oa-domain.com/api/workflow/paService/doCreateRequest' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'token: your_token_here' \
  -H 'appid: your_appid_here' \
  -H 'userid: your_encrypted_userid_here' \
  -d 'workflowId=388024' \
  -d 'requestName=测试流程标题' \
  -d 'remark=测试意见' \
  -d 'requestLevel=2' \
  -d 'mainData=[{"fieldName":"cswb","fieldValue":"2978"}]' \
  -d 'detailData=[{"tableDBName":"formtable_main_1356_dt1","workflowRequestTableRecords":[{"recordOrder":0,"workflowRequestTableFields":[{"fieldName":"dhwb","fieldValue":"第一行"},{"fieldName":"drl","fieldValue":"2978"}]}]}]' \
  -d 'otherParams={"isnextflow":0,"delReqFlowFaild":0}'

返回成功示例：

{
  "code": "SUCCESS",
  "data": {
    "requestid": 1699718
  },
  "errMsg": {},
  "reqFailMsg": {
    "keyParameters": {},
    "msgInfo": {},
    "otherParams": {}
  }
}

拿到 requestid 就说明流程创建成功了，这个 ID 就是流程实例的唯一标识。

小白专区：一步一步来

如果上面的 curl 你看得一头雾水，别慌，丸子下面一个一个讲。

第一步：这个接口是干嘛的？

简单说：通过代码自动新建一条泛微流程。

平时你在 OA 系统里点”新建流程”，选流程、填表单、点提交——这个接口就是把这个过程用 HTTP 请求来完成。

第二步：请求地址和方式

POST https://你的 OA 地址/api/workflow/paService/doCreateRequest

请求方式：POST（不是 GET！）
Content-Type：必须是 application/x-www-form-urlencoded（不是 JSON！）

💊 这里是个常见坑。很多人习惯用 JSON 格式发请求，但这个接口要求的是表单格式。

参数名	说明	怎么获取
token	调用凭证	通过泛微许可接口获取
appid	许可证号码	泛微后台配置
userid	加密后的用户 ID	用 spk 公钥加密 userid 得到
Content-Type	内容类型	固定填 `application/x-www-form-urlencoded`

这三个参数（token、appid、userid）是泛微 REST 接口的”通行证”，没有它们接口直接拒绝。

第四步：请求体（Body）参数详解

这是重点，一共就这几个参数：

workflowId（必填）—— 流程 ID

-d 'workflowId=388024'

这个数字是你要新建的流程模板 ID。怎么找？在 OA 系统里打开流程设计器，URL 里一般就有，或者查数据库 workflow_base 表。

requestName（必填）—— 流程标题

-d 'requestName=测试流程标题'

就是流程发起后显示的标题，随便填。

mainData（必填）—— 主表数据这个稍微复杂点，它是一个 JSON 数组，每个元素代表一个字段：

[
  {
    "fieldName": "cswb",
    "fieldValue": "2978"
  },
  {
    "fieldName": "csfjsc",
    "fieldValue": [
      {
        "fileName": "通用测试模板.xls",
        "filePath": "base64:AAA..."
      },
      {
        "fileName": "通用测试 pdf.pdf",
        "filePath": "https://example.com/sample.pdf"
      }
    ]
  }
]

fieldName：字段的数据库名称（不是显示名称！）。去表单设计器里看，或者查 workflow_formfield 表。
fieldValue：字段值。普通字段直接填字符串，附件字段比较特殊，需要传数组，每个附件包含 fileName（文件名带后缀）和 filePath（base64 编码或 URL）。

怎么找字段的数据库名称？进入表单设计器 → 点击字段 → 查看属性 → 有个”数据库字段名”就是了。

detailData（可选）—— 明细表数据如果你的流程有明细表，就用这个参数：

[
  {
    "tableDBName": "formtable_main_1356_dt1",
    "workflowRequestTableRecords": [
      {
        "recordOrder": 0,
        "workflowRequestTableFields": [
          {
            "fieldName": "dhwb",
            "fieldValue": "第一行"
          },
          {
            "fieldName": "drl",
            "fieldValue": "2978"
          }
        ]
      },
      {
        "recordOrder": 0,
        "workflowRequestTableFields": [
          {
            "fieldName": "dhwb",
            "fieldValue": "第 2 行"
          },
          {
            "fieldName": "drl",
            "fieldValue": "2978"
          }
        ]
      }
    ]
  }
]

tableDBName：明细表的数据库名，格式一般是 formtable_main_xxx_dt1。
workflowRequestTableRecords：每一行明细数据。
- recordOrder：行序号，从 0 开始。
- workflowRequestTableFields：和主表一样，fieldName + fieldValue。

多个明细表怎么办？在数组里加另一个 tableDBName 的对象就行。

remark（可选）—— 签字意见

-d 'remark=测试意见'

流程发起时的签字意见，不填就用流程默认的。

requestLevel（可选）—— 紧急程度

-d 'requestLevel=2'

数字越大越紧急，具体取值看你们流程的配置。

otherParams（可选）—— 扩展参数

-d 'otherParams={"isnextflow":0,"delReqFlowFaild":0}'

这是一个 JSON 对象，支持以下参数：

参数名	说明	可选值
isnextflow	新建后是否自动流转到下一节点	0：不流转，1：流转（默认）
delReqFlowFaild	新建失败是否自动删除流程	0：不删除，1：删除（默认）
isVerifyPer	是否验证用户创建权限	0：不验证，1：验证（默认）
requestSecLevel	流程密级	需开启密级功能才生效

isnextflow=0 什么意思？就是流程创建后停留在第一个节点，不自动往下走。有时候你还需要在第一个节点做点操作，就可以设成 0。

第五步：返回值怎么判断？

{
  "code": "SUCCESS",
  "data": {
    "requestid": 1699718
  }
}

code 为 SUCCESS → 成功，data.requestid 就是新建的流程 ID。
code 为 PARAM_ERROR → 参数有错，看 errMsg 里的具体提示，当然，一般没有，慢慢调吧~
code 为 NO_PERMISSION → 没有权限，检查 workflowId 对应的流程是否允许当前用户创建。
code 为 SYSTEM_INNER_ERROR → 服务端异常，看 OA 日志。

常见错误排查

错误现象	可能原因
workflowId 返回 -1	mainData 格式不对，多了 } 或 ]
mainData: 新建流程主表数据不允许为空	mainData 没传或者为空
error_param_xxx: ‘值’	某个字段名写错了，或者值不合法
返回 NO_PERMISSION	当前用户没有该流程的创建权限
返回 PARAM_ERROR 但 errMsg 为空	检查 Content-Type 是不是 `application/x-www-form-urlencoded`

小结

这个接口其实不难，核心就三个东西：

请求头：token、appid、userid（泛微接口三件套）
主表数据：mainData，字段名一定要和表单里的数据库字段名一致
明细表数据：detailData，结构比主表多一层”表名”和”行记录”

记住一个原则：字段名写错 = 报错，格式不对 = 报错，权限没有 = 报错。

好了，丸子喂饭完毕，希望你能吃饱~

有问题欢迎评论区留言~

参考资料与致谢

泛微官方文档：泛微E9后端接口说明（https://e-cloudstore.com/ec/api/applist/index.html#/）

引言