报销系统对接金蝶云星空：凭证推送字段与常见报错

对接的难点从来不是接口怎么调，而是辅助核算维度怎么传、账期状态怎么校验——这两处是报错的主要来源。接口本身有标准文档，照着写就行；真正花时间的是把费控侧的部门、项目、员工编码，和金蝶那边的基础资料对齐。

凭证推送的必需字段

辅助核算是最容易卡住的一环

金蝶的科目可以挂多个核算维度，而且不同科目要求的维度不一样。管理费用可能只要部门，研发支出还要项目，其他应付款要员工。

如果费控侧不知道每个科目要求哪些维度，就只能全部都传或者全部不传——前者可能传了科目不接受的维度，后者会因为缺维度被拒。

正确做法是在费控侧的科目主数据里维护 required_dims 字段，凭证生成时按科目要求填充并校验，缺什么在草稿阶段就报出来。

编码对不上怎么办

费控系统里的部门编码，未必和金蝶基础资料里的一致，尤其是费控用了 OA 或 HR 的组织架构时。

这时候需要一张编码转换对照表：费控侧编码 → 金蝶侧编码。这张表要在实施阶段就建立并维护，不要指望两边编码天然一致。

调研阶段必须问清楚的一个问题就是：维度值的编码两边是否一致，不一致是否需要转换表。

五类常见报错

这五类里，前四类都应该在推送之前就被拦下来。等金蝶返回错误码再排查，财务看到的是技术信息，既不知道哪张单出问题，也不知道该怎么改。

幂等：同一张单不能推出两张凭证

接口超时、网络抖动、人工重试，都可能导致同一张报销单被推送多次。必须在数据库层面建立唯一索引，用「报销单号 + 业务类型」作为唯一键，而不是仅靠应用层判断——并发情况下应用层判断会失效。

失败重试的状态机

失败原因必须完整记录并以可读方式呈现给财务，而不是只存一个错误码。

作废用红冲，不要删除

报销单作废或退回时，应生成红字凭证冲回，原凭证保留。原因有两点：会计档案完整性要求，以及总账系统通常不允许删除已过账凭证。