ERP 推送宜搭数据接口文档

1. 接口说明

ERP（T100）向明磊业务集成服务推送单据数据。当前接口仅负责接收和记录请求数据，暂不调用宜搭、不发起宜搭流程、不保存数据库。

2. 基本信息

项目	内容
接口名称	ERP 推送宜搭数据
请求方式	`POST`
请求地址	`http://10.0.0.250/api/erp/yida/push`
请求格式	`application/json`
返回格式	`application/json`
当前处理方式	接收入参、打印日志、返回成功
当前支持类型	`type` 非空即可，暂不限制类型白名单
`cpmp402` 对应单据	包材核价单通知
`cpmp402` 目标宜搭应用	`APP_RJJL69QUIZVQSV7YC8TL`

3. 请求头

Content-Type: application/json

4. 请求参数

4.1 请求体

{
  "type": "cpmp402",
  "mainData": {
    "rq": "2026-09-07",
    "bm": "采购部",
    "tjr": "ERP_USER_001",
    "gs": "明磊锂能有限公司",
    "t100id": "T100_USER_001",
    "ent": "CN",
    "t100bm": "PURCHASE"
  },
  "detailData": [
    {
      "hjdh": "HJ20260907001",
      "gysbh": "SUP001",
      "gysmc": "供应商名称",
      "t100id": "T100_SUP001",
      "ent": "CN",
      "yy": "zh_CN"
    }
  ]
}

4.2 顶层字段

字段	类型	必填	说明
`type`	`String`	是	单据类型标识。`cpmp402` 表示包材核价单通知，对应宜搭应用 `APP_RJJL69QUIZVQSV7YC8TL`。当前只校验非空，不限制具体值。
`mainData`	`Object`	是	固定主数据对象。
`detailData`	`Array/Object`	是	明细数据节点。必须传入，不校验具体 JSON 类型，可以是数组或对象。

4.3 `mainData` 字段

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

mainData 中除 tjr 外的字段可以传空字符串、空值或不填写。建议 ERP 端按约定字段完整传输，便于后续接入宜搭时直接映射。

4.4 `detailData` 明细字段

detailData 的格式不做校验，允许根据 type 对应的单据类型传入数组、对象或其他 JSON 结构。对于当前 ERP 推送格式，也支持在 detailData 外层再包一层 detailData 对象。

以 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() 生成，当前不返回 ERP 推送的业务数据或处理结果。

6. 参数校验失败

以下情况会被拒绝：

type 缺失或为空白字符串。
mainData 缺失或为 null。
mainData.tjr 缺失或为空白字符串。
detailData 缺失或为 null。
请求 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 可以为空数组：

{
  "type": "cpmp402",
  "mainData": {
    "tjr": "ERP_USER_001"
  },
  "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. 日志说明

请求成功进入 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 端避免传输无关敏感字段；后续如接入敏感字段，需要增加日志脱敏策略。

8. 调用示例

8.1 PowerShell

$body = @{
    type = "cpmp402"
    mainData = @{
        rq = "2026-09-07"
        bm = "采购部"
        tjr = "ERP_USER_001"
        gs = "明磊锂能有限公司"
        t100id = "T100_USER_001"
        ent = "CN"
        t100bm = "PURCHASE"
    }
    detailData = @(
        @{
            hjdh = "HJ20260907001"
            gysbh = "SUP001"
            gysmc = "供应商名称"
            t100id = "T100_SUP001"
            ent = "CN"
            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

8.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-07",
      "bm": "采购部",
      "tjr": "ERP_USER_001",
      "gs": "明磊锂能有限公司",
      "t100id": "T100_USER_001",
      "ent": "CN",
      "t100bm": "PURCHASE"
    },
    "detailData": [
      {
        "hjdh": "HJ20260907001",
        "gysbh": "SUP001",
        "gysmc": "供应商名称",
        "t100id": "T100_SUP001",
        "ent": "CN",
        "yy": "zh_CN"
      }
    ]
  }'

9. 单据类型映射

`type`	单据名称	目标宜搭应用	当前状态
`cpmp402`	包材核价单通知	`APP_RJJL69QUIZVQSV7YC8TL`	仅接收并记录 ERP 推送数据，暂不调用宜搭

10. 当前处理边界

当前不调用宜搭接口。
当前不发起宜搭流程。
当前不根据 type 分发具体单据处理器。
当前不校验 cpmp402 以外的单据类型。
当前不持久化 ERP 推送数据。
后续接入宜搭时，cpmp402 应路由至宜搭应用 APP_RJJL69QUIZVQSV7YC8TL 下的包材核价单通知表单，并根据 type 增加单据类型处理器和字段映射逻辑。

ERP-YIDA-PUSH-API.md 7.1 KB Cronologia Originale