ERP 推送宜搭数据接口文档

1. 接口说明

ERP（T100）向明磊业务集成服务推送单据数据。当前接口按 type 分发到对应的宜搭处理器，支持发起宜搭流程。

2. 基本信息

项目	内容
接口名称	ERP 推送宜搭数据
请求方式	`POST`
请求地址	`http://10.0.0.250/api/erp/yida/push`
请求格式	`application/json`
返回格式	`application/json`
当前处理方式	接收入参、打印日志、按 `type` 路由到宜搭流程处理器
当前支持类型	`cpmp402`、`csfp340`
`cpmp402` 对应单据	包材核价单通知
`csfp340` 对应单据	ML-工单工艺工价审定
目标宜搭应用	`APP_RJJL69QUIZVQSV7YC8TL`

3. 请求头

Content-Type: application/json

4. 请求参数

4.1 请求体

{
  "type": "cpmp402",
  "mainData": {
    "rq": "2026-09-08",
    "bm": "ML07000000",
    "tjr": "3075",
    "gs": "ML",
    "t100id": "ML",
    "ent": 87,
    "t100bm": "ML07000000"
  },
  "detailData": {
    "detailData": [
      {
        "hjdh": "MLCH326090800001",
        "gysbh": "113009",
        "gysmc": "南京鼎泰五金工具有限公司",
        "t100id": "ML",
        "ent": "87",
        "yy": "zh_CN"
      }
    ]
  }
}

4.2 顶层字段

字段	类型	必填	说明
`type`	`String`	是	单据类型路由键。`cpmp402` 表示包材核价单流程；`csfp340` 表示 `ML-工单工艺工价审定` 流程。
`mainData`	`Object`	是	固定主数据对象。
`detailData`	`Object`	是	明细数据外壳。必须是对象，且内部必须包含 `detailData` 数组。

4.3 `mainData` 字段

字段	类型	必填	说明
`rq`	`String`	否	日期（yyyy-MM-dd）。
`bm`	`String`	否	部门（钉钉部门编号）。
`tjr`	`String`	是	提交人（工号），不能为空字符串或空白字符。
`gs`	`String`	否	公司（代码）。
`t100id`	`String`	否	T100 用户或业务对象标识。
`ent`	`String`	否	地区（代码）。
`t100bm`	`String`	否	T100 部门。

mainData 中除 tjr 外的字段可以传空字符串、空值或不填写。服务端会统一处理 mainData：tjr 按员工花名册的工号查询钉钉 userId，并作为宜搭流程发起人；rq、bm、gs、t100id、ent、t100bm 会作为通用默认元数据补入内部明细对象，供后续所有走通用接口的 type 复用。若工号不存在或没有钉钉 ID，接口返回 HTTP 400。

4.4 `detailData` 明细字段

detailData 的外层结构固定为对象，且必须包含 detailData 数组。数组内对象字段根据 type 对应的单据类型定义；后续所有走通用接口的类型都必须遵守该结构。

以 cpmp402 包材核价单通知为例，推荐字段如下：

字段	类型	必填	说明
`hjdh`	`String`	否	核价单号。
`gysbh`	`String`	否	供应商编号。
`gysmc`	`String`	否	供应商名称。
`t100id`	`String`	否	T100 业务对象标识。
`ent`	`String`	否	地区。
`yy`	`String`	否	语言。

接口不会校验明细对象的具体字段，后续新增单据类型或单据字段时，可直接扩展请求内容。

5. 成功响应

HTTP 状态码：200 OK

响应示例：

{
  "success": true,
  "code": "200",
  "message": "SUCCESS"
}

该响应由基座 com.malk.server.common.McR 的 McR.success() 生成；宜搭流程实例号会写入服务日志。

6. 参数校验失败

以下情况会被拒绝：

type 缺失或为空白字符串。
mainData 缺失或为 null。
mainData.tjr 缺失或为空白字符串。
mainData.tjr 对应工号在员工花名册中不存在，或该员工没有钉钉 userId。
detailData 缺失、为 null、不是对象，或不包含数组字段 detailData.detailData。
请求 JSON 格式错误。

HTTP 状态码：400 Bad Request

示例：

{
  "timestamp": "2026-09-07T13:50:00.000+00:00",
  "status": 400,
  "error": "Bad Request",
  "path": "/api/erp/yida/push"
}

detailData.detailData 可以为空数组：

{
  "type": "cpmp402",
  "mainData": {
    "tjr": "3075"
  },
  "detailData": {
    "detailData": []
  }
}

也可以使用对象格式：

{
  "type": "cpmp402",
  "mainData": {
    "rq": "2026-09-08",
    "bm": "ML07000000",
    "tjr": "3075",
    "gs": "ML",
    "t100id": "ML",
    "ent": 87,
    "t100bm": "ML07000000"
  },
  "detailData": {
    "detailData": [
      {
        "hjdh": "MLCH326090800001",
        "gysbh": "113009",
        "gysmc": "南京鼎泰五金工具有限公司",
        "t100id": "ML",
        "ent": "87",
        "yy": "zh_CN"
      }
    ]
  }
}

7. 宜搭调用失败

当底层宜搭或钉钉接口返回错误时，HTTP 状态码为 502 Bad Gateway，响应会返回上游错误码和错误信息，便于定位字段格式、权限或配置问题：

{
  "code": "DINGTALK_YIDA_ERROR",
  "message": "上游字段校验失败"
}

如果响应仍为 YIDA_CALL_FAILED，说明不是宜搭业务错误码，而是网络、JSON 序列化或其他未分类异常；此时需要查看应用错误日志中的异常堆栈。

csfp340 会复用通用 mainData 处理结果：mainData.tjr 会按工号查询员工花名册，取 dingtalk_id 作为流程发起人并写入申请人字段 employeeField_msh186rr；mainData.rq 作为默认申请日期；mainData.gs 写入申请公司字段 textField_mu1yk6l5；mainData.bm 部门 ID 直接以数组写入申请部门字段 departmentSelectField_msh186ry。

8. 日志说明

请求成功进入 Service 后，会记录以下两类 INFO 日志：

ERP Yida push request: {请求 JSON}
ERP Yida push response: {McR 响应 JSON}

示例：

ERP Yida push request: {"type":"cpmp402","mainData":{"tjr":"ERP_USER_001"},"detailData":[]}
ERP Yida push response: {"success":true,"code":"200","message":"SUCCESS"}

当前日志记录的是完整业务请求内容，以及宜搭返回的流程实例号。生产环境如请求中包含密码、令牌或其他敏感信息，应在 ERP 端避免传输无关敏感字段；后续如接入敏感字段，需要增加日志脱敏策略。

9. 调用示例

9.1 PowerShell

$body = @{
    type = "cpmp402"
    mainData = @{
        rq = "2026-09-08"
        bm = "ML07000000"
        tjr = "3075"
        gs = "ML"
        t100id = "ML"
        ent = 87
        t100bm = "ML07000000"
    }
    detailData = @{
        detailData = @(
            @{
                hjdh = "MLCH326090800001"
                gysbh = "113009"
                gysmc = "南京鼎泰五金工具有限公司"
                t100id = "ML"
                ent = "87"
                yy = "zh_CN"
            }
        )
    }
} | ConvertTo-Json -Depth 10

Invoke-RestMethod `
    -Method Post `
    -Uri "http://10.0.0.250/api/erp/yida/push" `
    -ContentType "application/json" `
    -Body $body

9.2 curl

curl -X POST "http://10.0.0.250/api/erp/yida/push" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "cpmp402",
    "mainData": {
      "rq": "2026-09-08",
      "bm": "ML07000000",
      "tjr": "3075",
      "gs": "ML",
      "t100id": "ML",
      "ent": 87,
      "t100bm": "ML07000000"
    },
    "detailData": {
      "detailData": [
        {
          "hjdh": "MLCH326090800001",
          "gysbh": "113009",
          "gysmc": "南京鼎泰五金工具有限公司",
          "t100id": "ML",
          "ent": "87",
          "yy": "zh_CN"
        }
      ]
    }
  }'

9.3 `csfp340` 流程发起示例

{
  "type": "csfp340",
  "bm": " ",
  "gs": "ML",
  "tjr": "241021001",
  "mainData": {
    "sfaaent": 87,
    "t100id": "ML",
    "sfaadocno": "MLJDB26060300002",
    "sfaaud009": null,
    "sfaa010": "101010128F0324100007",
    "imaal003": "充电式干墙枪",
    "imaal004": "ML-CD225(无刷)",
    "zzbz": "0",
    "zzbz1": "B",
    "cjzg": "62",
    "gdgj": 0
  },
  "detailData": {
    "detailData1": [
      {
        "sfbaent": 87,
        "sfbasite": "ML",
        "sfbaseq": 10,
        "sfba006": "B90101000000001",
        "imaal003": "定牌标贴",
        "imaal004": "PVC哑膜,38.5X15.5MM,CS63n",
        "yl": 1
      },
      {
        "sfbaent": 87,
        "sfbasite": "ML",
        "sfbaseq": 20,
        "sfba006": "B90101000000004512001",
        "imaal003": "可变-参数标贴",
        "imaal004": "PVC哑膜,43.4X30.5MM,64754/CD154不带冲击n",
        "yl": 1
      }
    ]
  }
}

该类型发起宜搭流程，流程表单名 ML-工单工艺工价审定，表单 UUID FORM-4403B45A7F184CB79088FCDAFD2FD925LZ3K，流程编码 TPROC--WG966BA1VWF8Q1K4OGF8H9KW47RR3ZREH0YSM2。字段 ID 已通过 OpenYida Schema 获取。

当前默认映射包括：sfaadocno→textField_msy0zj5i、sfaaud009→textField_msy0zj5j、sfaa010→textField_msy0zj5l、imaal003→textField_msy0zj5m、imaal004→textField_msy0zj5n、zzbz→textField_msy0zj5o、cjzg→numberField_msy0zj5q、gdgj→numberField_msy0zj5z；detailData1 写入 tableField_msh186t3，其中 sfbaseq、sfba006、imaal003、imaal004、yl 分别写入明细字段 textField_msy0zj65～textField_msy0zj69。本次按要求跳过关联字段 zzbz1（包装方式）。

10. 单据类型映射

`type`	单据名称	目标宜搭应用	当前状态
`cpmp402`	包材核价单	`APP_RJJL69QUIZVQSV7YC8TL`	已按 `type` 路由到宜搭流程处理器
`csfp340`	ML-工单工艺工价审定	`APP_RJJL69QUIZVQSV7YC8TL`	已按 `type` 路由到宜搭流程处理器

11. 当前处理边界

当前支持 cpmp402 和 csfp340。
当前 type 作为路由键，不作为表单 ID。
当前发起人 originatorUserId 由 mainData.tjr 工号通过员工花名册解析。
当前包材核价单表单 ID 和流程编码由代码中的 Cpmp402YidaProcessHandler 维护。
当前 ML-工单工艺工价审定 是流程表单，必须走流程发起接口；表单 ID 和流程编码由代码中的 MlWorkOrderCraftPriceFormPushHandler 维护。

ERP-YIDA-PUSH-API.md 10 KB Historie Surový