minglei/ERP-YIDA-PUSH-API.md

ERP 推送宜搭数据接口文档

1. 接口说明

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

2. 基本信息

项目	内容
接口名称	ERP 推送宜搭数据
请求方式	POST
请求地址	http://10.0.0.250/api/erp/yida/push
请求格式	application/json
返回格式	application/json
当前处理方式	接收入参、打印日志、按 type 路由到宜搭流程处理器
当前支持类型	cpmp402、ml_work_order_craft_price
cpmp402 对应单据	包材核价单通知
ml_work_order_craft_price 对应单据	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 表示包材核价单流程；ml_work_order_craft_price 表示 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 序列化或其他未分类异常；此时需要查看应用错误日志中的异常堆栈。

ml_work_order_craft_price 会复用通用 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 ml_work_order_craft_price 流程发起示例

{
  "type": "ml_work_order_craft_price",
  "mainData": {
    "rq": "2026-09-08",
    "tjr": "3075"
  },
  "detailData": {
    "detailData": [
      {
        "标题": "工单工艺工价审定-GD-001",
        "工单号": "GD-001",
        "生产令": "MO-001",
        "生产料号": "ITEM-001",
        "品名": "电池包",
        "规格": "24V",
        "组装|包装": "组装",
        "固定工价": "10.5",
        "总单位工价": "17.5",
        "明细表1": [
          {
            "工序编号": "GX-001",
            "名称": "装配",
            "数量": "2",
            "工价": "3.5",
            "合计": "7.0"
          }
        ],
        "明细表2": [
          {
            "项次": "10",
            "料号": "MAT-001",
            "品名": "电池盒",
            "规格": "A1",
            "用量": "1.2",
            "t100id": "ML",
            "车间线长": "leader-001",
            "企业编号": "87"
          }
        ]
      }
    ]
  }
}

该类型发起宜搭流程，流程表单名 ML-工单工艺工价审定，表单 UUID FORM-4403B45A7F184CB79088FCDAFD2FD925LZ3K，流程编码 TPROC--WG966BA1VWF8Q1K4OGF8H9KW47RR3ZREH0YSM2。字段 ID 已通过 OpenYida schema 获取，服务端支持中文字段名、常见英文/拼音字段名，也支持调用方在 detailData.detailData[] 的明细对象中直接传入宜搭 fieldId 覆盖默认映射。

申请人、申请公司和申请部门对应字段固定为：

• 申请人：employeeField_msh186rr，固定由 mainData.tjr 工号查询员工花名册后取 dingtalk_id 写入。
• 申请公司：textField_mu1yk6l5，优先取 mainData.gs；mainData.gs 为空时可用明细中的 申请公司、applyCompany、company 兜底。
• 申请部门：departmentSelectField_msh186ry，优先取 mainData.bm 部门 ID 直接写入；mainData.bm 为空时可用明细中的 申请部门、applyDepartment、department、deptId 兜底。

如果 mainData.gs 或 mainData.bm 为空，需要在明细中兜底申请公司和申请部门，请传申请公司文本值与钉钉部门 ID：

{
  "detailData": {
    "detailData": [
      {
        "申请公司": "浙江明磊锂能源科技股份有限公司",
        "申请部门": ["123456"]
      }
    ]
  }
}

10. 单据类型映射

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

11. 当前处理边界

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