# 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. 请求头 ```http Content-Type: application/json ``` ## 4. 请求参数 ### 4.1 请求体 ```json { "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` 响应示例： ```json { "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` 示例： ```json { "timestamp": "2026-09-07T13:50:00.000+00:00", "status": 400, "error": "Bad Request", "path": "/api/erp/yida/push" } ``` `detailData.detailData` 可以为空数组： ```json { "type": "cpmp402", "mainData": { "tjr": "3075" }, "detailData": { "detailData": [] } } ``` 也可以使用对象格式： ```json { "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`，响应会返回上游错误码和错误信息，便于定位字段格式、权限或配置问题： ```json { "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` 日志： ```text ERP Yida push request: {请求 JSON} ERP Yida push response: {McR 响应 JSON} ``` 示例： ```text 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 ```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 ```bash 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` 流程发起示例 ```json { "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： ```json { "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` 维护。