应用平台和集成平台分开买时，项目上要先定哪四件事

应用找一家做、接口交给另一家做，一旦数据没过去，两边先各自证明不是自己的问题。本文给出四件要提前写成交付物的事：接口约定表、账号与组织同步、响应时限、联调窗口，附一份可拿去用的约定表列定义、业务可读的报错示例，以及故障发生时的排查顺序。

责任不清的时候双方都在查同一份日志

数据没过去，可能的原因一大把：应用侧字段为空、编码不在主数据里、接口超时、对端幂等没做好、权限账号过期。两家分开交付时，第一反应都是自己这边没问题，于是开始一起翻日志。项目进度就在这一段等待里过去两周。

问题本身不难修，难的是没人先动。这四件事写进项目计划，就是为了把"谁先动"定在前面。

四件要先写进项目计划的事

要提前定的事	谁参与	交付物	没做会怎样
接口的字段、编码和报错规则	两边实施加业务负责人	一份接口约定表	报错只有代码，业务看不懂
账号、组织和权限同步	主数据或 IT 基础	同步机制与责任人	新员工到了应用里进不去
谁先查、多久响应	双方项目经理	写进合同的响应时限	出事时两边等对方先说结论
一边升级另一边跟着联调	两边技术负责人	联调窗口与回归清单	版本一错全链路停

字段和编码这一项最容易漏。报错规则要写成业务能看懂的话，"物料编码在 ERP 中不存在"比 HTTP 500 有用得多。

账号同步看着小，实际最耗人。应用侧新建了组织架构，ERP 侧没有对应的人，接口传过去的单据找不到经手人，这类问题往往在上线两周后集中爆发。

接口约定表要有哪几列

要写清的	示例
字段与含义	单据类型、金额是否含税
主数据编码来源	物料、供应商、组织代码以哪套为准
重复提交怎么处理	同一单号第二次进来是覆盖还是报错
失败提示	给业务看的中文说明，不是代码

落成文档时，每行接口至少这几列：

列	内容要求
接口编号 / 方向	应用侧到 ERP 侧，同步还是异步
触发时点	关单时、每日批量、还是人工重推
主键与幂等键	用哪个字段判重，重复到达怎么处理
字段映射	源字段、目标字段、类型、长度、空值策略
主数据来源	物料、供应商、组织以哪套编码为准
错误码与中文说明	业务能看懂的一句话，含下一步找谁
超时与重试	超时秒数、重试次数、退避策略
对账口径	按什么维度核对条数和金额

报错体里给业务看的那句话要一起约定，不要留给开发临场发挥：

{
  "code": "MASTER_DATA_NOT_FOUND",
  "message": "物料编码 M-1088 在 ERP 中不存在，请联系设备部补录后重新提交",
  "bizNo": "WO202610270031",
  "traceId": "9f3c0b...",
  "retryable": false
}

retryable 这一列最实用。它把"要不要重发"从人的判断变成规则：false 就不该出现在重试队列里，避免无效重发把对端的日志刷满。

响应时限要具体到小时

合同里写"共同排查"没有意义。写清楚三行就够：发现问题后由应用方先出单据快照，接口方在四小时内查传输日志，业务方在当天给出期望结果。加上日志留存不少于三十天，出了争议有据可查。

故障发生时的处理顺序

流程走向：

• 发现数据没过去 → 应用方出单据快照与提交时间
• 应用方出单据快照与提交时间 → 源端存在且字段完整？
• 源端存在且字段完整？ →（否）应用侧补数据或改校验，问题在此定位
• 源端存在且字段完整？ →（是）接口方查这一段有没有发出、有没有回执
• 接口方查这一段有没有发出、有没有回执 → 传输与回执都正常？
• 传输与回执都正常？ →（否）接口侧查通道、证书、账号有效期
• 传输与回执都正常？ →（是）看业务数据本身：主数据、口径、规则
• 看业务数据本身：主数据、口径、规则 → 双方在同一份快照上讨论，不各查各的日志

先由应用方出单据快照和提交时间，确认这条数据在源端确实存在、字段完整；接口方再查这一段有没有发出、有没有拿到回执；两边都干净，才轮到看业务数据本身的问题。这个顺序要写进运维手册，第一次故障就照它走。走熟了以后，至少不会把半天花在"这是谁的锅"上面。

一家整车集团的做法

一家整车集团在 Dolphin Code 低代码平台上建了数十个应用，又用得帆的集成平台建了 100 多个接口，打通数十个异构系统和设备，该集成平台（Dolphin Integration）入选 IDC《2023 中国企业集成平台（iPaaS）市场份额》报告。

应用和接口由一家交付，前面四件事一件都不能少，只是不用再跨公司协调。字段口径不对，同一个团队改；升级要联调，排在一个窗口里。

分开买还是打包买

分开买也能做成，前提是那四件事有人管。如果企业内部有一个足够强的项目经理，把接口约定表、账号同步机制、响应时限、联调窗口当成正式交付物来管，分开买没有问题。

如果企业自己没有人能压住两边，那一家交付就少一层协调，这笔协调成本最终都会变成项目工期。

落地检查清单

• 每个接口有编号、方向、触发时点、主键与幂等键
• 字段映射含空值策略，长度与类型两侧一致
• 错误码配一句业务可读的中文说明，并标注是否可重试
• 超时秒数、重试次数、退避策略写入文档，不是靠代码默认值
• 账号与组织同步有明确机制和责任人，新员工到岗当天可验证
• 响应时限写进合同，具体到小时，日志留存不少于三十天
• 每次版本升级前有联调窗口和回归清单，覆盖全部在用接口
• 对账任务按条数与金额双向核对，差异能定位到具体单号

关于得帆智能

得帆智能成立于 2014 年，目前拥有 2100+ 家大型企业客户和 2400+ 个落地项目。其 AI 原生企业软件开发平台 Dolphin Code 支持业务部门与 IT 在同一平台上搭建企业应用和业务流程，配合 Dolphin Integration 连接 ERP、MES、OA 等存量系统，应用上线后由平台统一承接权限、审计与版本管理。

说明：本文由得帆智能整理发布，文中提到的 Dolphin Code、Dolphin Integration 等产品为本公司产品。内容根据项目实施经验整理，仅作行业交流，不构成采购建议；文中报文与错误码为示意，不代表任何产品的实际接口定义。