开放接口清单与调用说明

模块定位

开放接口让 MES 与 ERP、WMS、PLM、SCADA 等系统交换数据。

接口分类

认证方式

推荐 OAuth 2.0 + IP 白名单组合。

调用规范

请求

响应

统一格式：

"错误码要区分系统错误和业务错误"：

• 系统错误（500）：服务异常，可重试
• 业务错误（400）：参数或业务规则问题，不要重试

关键接口设计原则

1. 幂等性

创建类接口要支持幂等：同一个请求重复提交，结果一致。

实现方式：请求方带唯一的 requestId，服务端记录已处理的 requestId。

这是最容易被忽略但最重要的设计。没有幂等，网络重试会产生重复数据。

2. 批量支持

支持批量提交，减少请求次数。

但要限制单批数量（比如 500 条），避免超时和内存问题。

3. 增量同步

数据同步优先用增量（按更新时间拉取），而非全量。

接口要支持按时间范围查询。

4. 版本管理

接口要有版本号（/api/v1/、/api/v2/），便于升级时不破坏老调用方。

5. 限流

服务端要限流，防止调用方异常导致服务过载。

调用方也要控制频率，遵守对方的限流规则。

集成注意事项

"对账机制"强烈建议加上。每天定时比对关键数据（工单数、完工量、库存），不一致就告警。

不做对账，问题往往几周后才发现，追溯成本极高。

重试策略

重试必须配合幂等。

日志与追踪

接口调用要记录：

• 请求时间、耗时
• 请求参数（敏感字段脱敏）
• 响应结果
• traceId

traceId 用于跨系统追踪，出问题时能快速定位。

关键配置项

常见问题

接口清单、参数说明与调用示例，[待补充：产品团队补齐]。