心理测评 API 接入业务系统，看起来是技术对接，真正容易出错的是字段契约。用户是谁，属于哪个组织，参加哪个项目，用的是哪个量表版本，报告处在什么状态，这些口径先定清楚，接口才会稳定。
HR 系统、教务系统、预约系统、CRM、体检系统和咨询档案系统都有自己的用户结构。心理测评 API 接入时，传一个链接远远不够。
用户标识要稳定
手机号、工号、学号、身份证号、客户编号、openid 都可能被拿来确认用户。它们的稳定性、隐私等级和适用场景各有差异。
企业适合使用员工编号或内部用户 ID，学校适合使用学号或教务系统 ID，咨询机构适合使用来访者档案 ID。手机号可以用于通知，身份主键要跟业务系统保持一致。
橙星云在 API 接入时，应把用户 ID、组织 ID、项目 ID、批次 ID 和量表 ID 分开。这样后续查报告、撤回任务、补发测评和导出数据时，才会落到正确对象。
报告状态要细到业务动作
报告状态要细到业务动作。已创建、已发放、已打开、已作答、已生成报告、待人工复核、已复核、已撤回、已过期，对应不同处理流程。
量表版本同样要进入字段。老报告要能追溯当时使用的题目、计分和解释文案。心理测评质控可参考心理测评质控系统怎么用，量表报告和权限日志要定期核对。
回传范围要写进接口文档
业务系统可能只需要报告链接、完成状态、风险分层和摘要。完整作答、维度分、原始分和解释文本，应按业务必要性开放。
API 日志要记录请求方、时间、用户、报告、IP、接口和返回状态。发生数据疑问时，技术团队和业务团队都能查到证据。
心理测评 API 接入的重点，是先定字段契约。用户标识、量表版本、报告状态、权限范围和回传内容清楚之后，接口开发才有稳定基础。