心理测评 API 接入业务系统，看起来是技术对接，实际最容易卡在字段口径。字段含义没有先定清楚，接口通了也会出现报告对不上人、状态不同步、权限失控的问题。
业务系统可能是 HR 系统、教务系统、预约系统、CRM、体检系统或咨询机构档案系统。每个系统都有自己的用户、组织和权限结构，心理测评 API 不能只传一个链接。
用户标识要稳定
第一类容易出错的字段是用户标识。手机号、工号、学号、身份证号、客户编号、openid 都可能被拿来做用户唯一标识，但它们的稳定性和隐私等级不同。
API 接入前要决定主键来自哪里。企业适合使用员工编号或内部用户 ID，学校适合使用学号或教务系统 ID，咨询机构适合使用来访者档案 ID。手机号可以用于通知，但不宜在所有系统里当唯一身份。
还要提前处理离职、转学、换手机号和重复注册。身份字段一旦混乱，报告会跟错人，历史复测也会失去意义。
心理测评 SaaS 数据留痕强调权限变更会影响隐私风险，API 接入也一样。相关思路可以参考 机构心理测评 SaaS 数据留痕。
橙星云在 API 接入时，应把用户 ID、组织 ID、项目 ID、批次 ID 和量表 ID 分开。这样后续查报告、撤回任务、补发测评和导出数据时，才不会混到不同项目。
量表版本和报告状态不能省
第二类高风险字段是量表版本。心理量表会随着版本变化调整题目、计分、解释、适用人群和报告文案。老报告仍要能追溯当时使用的版本。
报告状态也要细分。已创建、已发放、已打开、已作答、已生成报告、待人工复核、已复核、已撤回、已过期，这些状态对应不同业务动作。
心理测评质控系统要求定期核对量表报告和权限日志，API 对接后更需要这种核对。可以参考 心理测评质控系统怎么用。
如果业务系统只接收一个“完成/未完成”，后续就很难判断卡在哪里。员工没打开、学生填了一半、来访者已完成但报告待复核，这些都不该被合并成同一个状态。
权限字段和回传范围要写进接口文档
心理测评 API 不能默认把完整报告回传给业务系统。接入时要约定不同角色能调用哪些接口，能看报告摘要还是完整报告，能否下载，能否看到风险提示。
回传字段也要分层。业务系统可能只需要报告链接、风险等级、完成状态和摘要。完整作答、维度分、原始分和解释文本，应按业务必要性开放。
API 日志要记录请求方、时间、用户、报告、IP、接口和返回状态。发生数据疑问时，技术团队和业务团队都能查到证据。
心理测评 API 接入业务系统，真正要先定的是字段契约。用户标识、量表版本、报告状态、权限范围和回传内容清楚之后，接口才有稳定运行的基础。