コンテンツへスキップ
首页 » HEXACO-JP API文档｜REST API集成与诊断结果获取指南

HEXACO-JP API文档｜REST API集成与诊断结果获取指南

本文将详细介绍HEXACO-JP API文档的核心内容，帮助开发者快速理解如何将HEXACO人格测评功能集成到自有服务中。无论您是构建HR招聘平台、员工培训系统，还是心理健康应用，本指南都将提供完整的REST API集成流程、API端点规范及响应数据格式说明，让您的项目开发文档更加清晰完备。

HEXACO人格测评是基于六大人格维度（诚实-谦逊、情感性、外向性、宜人性、尽责性、开放性）构建的科学评估工具。通过HEXACO-JP API，企业和开发者可以将这套经过验证的人格诊断能力直接嵌入自有产品，从而为用户提供个性化的诊断结果获取体验。使用API前，需要先在诊断网站完成项目创建并购买回答配额。

整体集成流程概览

整个REST API集成过程共分为5个关键步骤，每个步骤环环相扣，缺一不可。理解这一全局流程，有助于开发者在着手编码前建立清晰的系统架构认知。

  1. 在诊断网站创建项目，获取项目密钥（Project Key）、API密钥（API Key）及重定向URL
  2. 从自有服务将目标用户重定向至HEXACO-JP答题页面
  3. 用户完成约100道题目的作答并提交
  4. 提交完成后，系统将用户导回您指定的重定向URL，并附带响应ID等查询参数
  5. 利用查询参数通过REST API获取完整的诊断结果数据

这一流程的设计逻辑在于：答题与评分由服务端统一处理，开发者只需专注于数据对接与展示，无需自行维护复杂的心理测量算法。

STEP 1：创建项目并获取密钥

正确配置项目是整个API对接的基础，任何密钥错误都可能导致后续步骤失败。请登录诊断网站，从菜单中选择”商业用途”，然后新建一个项目。创建时需要配置以下参数：

  • 项目类型：选择”API”模式
  • 重定向URL：用户完成答题后将跳转至的自有网站地址（可在创建后修改）
  • 回答配额数量：预购的测评次数，每次费用为5美元（不含税）
  • 题目内容：HEXACO-JP标准版共100道题，预计作答时间约10分钟

项目创建完成后，在项目详情页面可以看到系统自动生成的项目密钥与API密钥。这2个密钥均支持重新生成，重定向URL也可随时在后台编辑更新，具有较高的灵活性。

STEP 2 & 3：引导用户跳转并完成答题

通过标准URL参数将用户重定向至答题页面，是实现无缝用户体验的关键设计。在自有服务中，通过按钮或链接将用户引导至以下URL：

https://personalities.me/biz/survey?token=<project_key>&sessionData=<session_data>

参数说明如下：

  • token：在项目详情页获取的项目密钥
  • sessionData：用于在自有系统中唯一标识该用户的任意URL编码字符串（例如用户的电子邮件地址）。此字段在答题完成后会原样返回，便于您将测评结果与内部用户记录进行关联

用户跳转后将进入HEXACO-JP的标准答题界面，完成约100道题目后点击提交。所有答题数据的存储与评分计算均由服务端完成，开发者无需在客户端做任何数据处理。

STEP 4：接收重定向回调与查询参数

用户提交答题后，系统会携带5个关键查询参数跳回您的重定向URL，这些参数是后续调用API获取诊断结果的核心依据。开发者需要在重定向落地页正确解析并存储这些参数。

  • projectId（GUID格式）：标识当前项目的唯一ID
  • surveyType（字符串，示例：hexaco-jp100）：测评类型标识
  • responseId（GUID格式）：本次答题记录的唯一ID
  • userId（GUID格式）：用户在系统中的唯一标识
  • sessionData：您在STEP 2中传入的自定义用户标识字符串，原样返回

以下是一个典型的重定向回调URL示例：

<HTTP_REDIRECT_URL>?responseId=e5f6ea19-eae0-4e07-a972-dbd94436c1e0
  &projectId=fc3980c8-7f51-47b3-b4cf-43fe1d62a3a0
  &surveyType=hexaco-jp100
  &userId=336bd9b8-fafc-4d98-9081-b2049d146205
  &sessionData=jay@amegumi.com

STEP 5：通过HEXACO-JP API文档规范的端点获取结果

最后一步是在自有服务器端调用REST API，将回调参数组合成完整的请求路径，并以Bearer格式携带API密钥进行认证。切记：API密钥绝对不能暴露在浏览器客户端，必须通过服务器端代理调用。

API端点规范

GET https://psych.sunblaze.jp/api/psych/v1/projects/{projectId}/surveys/{surveyType}/users/{userId}/responses/{responseId}

Authorization: Bearer <api_key>

以下是一个使用curl的实现示例，适合在服务器端脚本或CI/CD流程中快速验证接口连通性：

curl -X GET \
  "https://psych.sunblaze.jp/api/psych/v1/projects/${PROJECT_ID}/surveys/hexaco-jp100/users/${USER_ID}/responses/${RESPONSE_ID}" \
  -H "Authorization: Bearer ${API_KEY}"

响应数据格式解析（200 OK）

成功调用后，API将返回结构化的JSON数据，涵盖本次测评的完整信息：

{
  "responseId": "resp_xyz789",
  "projectId": "proj_abc123",
  "userId": "user_123",
  "email": "user@example.com",
  "surveyType": "hexaco-jp100",
  "status": "completed",
  "startedAt": "2025-12-24T10:00:00Z",
  "completedAt": "2025-12-24T10:15:00Z",
  "durationSeconds": 900,
  "scores": {
    "honesty_humility":  { "value": 3.45, "average": 3.2 },
    "emotionality":      { "value": 2.89, "average": 3.1 },
    "extraversion":      { "value": 4.12, "average": 3.5 },
    "agreeableness":     { "value": 3.67, "average": 3.3 },
    "conscientiousness": { "value": 3.91, "average": 3.4 },
    "openness":          { "value": 3.23, "average": 3.2 }
  },
  "facets": {
    "sincerity": 3.2,
    "fairness":  3.5
  },
  "tendencies": {
    "leadership": 72,
    "teamwork":   85
  }
}

响应数据中的3个核心字段含义如下：

  • scores：HEXACO六大维度的得分（value）及参照群体的平均值（average），可用于生成相对位置的可视化图表
  • facets：各维度下的子层面得分，例如诚实性下的”真诚度”与”公平性”，提供更细粒度的人格洞察
  • tendencies：包括领导力、团队合作等约90个行为倾向指标，以百分制呈现，便于直观展示与应用

HTTP状态码说明

  • 200 OK：请求成功，返回完整的诊断结果数据
  • 401 Unauthorized：API密钥无效或未在请求头中提供
  • 403 Forbidden：项目合同无效或配额已耗尽
  • 404 Not Found：指定的responseId不存在或尚未完成

常见问题解答

API密钥或项目密钥泄露了该怎么办？

如果发现密钥泄露，请立即登录诊断网站，进入项目详情页面，分别点击”重新生成API密钥”或”重新生成项目密钥”按钮。旧密钥将在重新生成后立即失效，所有使用旧密钥的请求将收到401错误响应。建议将密钥存储在服务器端的环境变量中，避免硬编码在代码库中。

重定向URL可以在项目创建后修改吗？

可以。重定向URL支持随时在项目详情页面进行修改，更新后对该项目下所有尚未使用的回答配额立即生效。这一设计方便开发者在测试阶段使用临时地址，正式上线后再切换为生产环境的URL，无需重新创建项目或重新购买配额。

回答配额是如何计费的？每次费用是多少？

回答配额采用预付费模式，在创建项目时一次性购买指定数量的测评次数，每次费用为5美元（不含税）。配额会在用户成功提交答题后扣减，若用户中途放弃作答则不计入消耗。详细计费规则请参考服务介绍页面。

sessionData参数支持哪些类型的数据？

sessionData接受任意URL编码的字符串，只要能在您的系统中唯一标识用户即可，例如用户的电子邮件地址、内部用户ID或UUID等。该字段的值在答题完成后会原样附加到重定向URL的查询参数中返回，便于您在服务器端将测评结果与数据库中的用户记录精确关联，无需额外存储映射表。

tendencies字段中包含哪些行为倾向指标？

研究表明，tendencies字段目前包含约90个行为倾向指标，涵盖领导力、团队合作、抗压能力、沟通风格等多个职场相关维度，以0至100的百分制呈现。这些指标是基于HEXACO六大维度得分经过模型换算得出的派生数据，可以直接用于员工能力评估报告或个人成长建议生成，具有较强的实际应用价值。

可以在客户端浏览器中直接调用API吗？

不建议这样做。API密钥若暴露在浏览器端代码中，存在被恶意用户获取并滥用的安全风险，可能导致配额被非法消耗甚至用户数据泄露。正确的做法是由您的服务器端代码接收重定向回调中的查询参数，再由服务器向HEXACO-JP API发起请求，最后将整理好的结果数据返回给前端展示层。

HEXACO-JP API与其他人格测评API相比有哪些优势？

HEXACO模型相比常见的五大人格（Big Five）模型，额外引入了”诚实-谦逊”这一独立维度，研究表明这一维度在预测道德行为、反社会倾向及职场诚信方面具有独特的区分效度。HEXACO-JP API将这套经过学术验证的测量工具以标准REST接口的形式提供，并包含约90个衍生行为倾向指标，适合需要深度人格洞察的商业应用场景。

总结与相关资源

本文系统梳理了HEXACO-JP API文档中的5步集成流程，涵盖项目创建、用户跳转、回调解析、REST API集成及响应数据格式的完整说明。从API端点规范到约90个行为倾向指标的响应结构，每个环节都经过精心设计，力求在保障数据安全的同时为开发者提供最大的灵活性。如果您正在为自有平台引入科学化的HEXACO人格测评能力，建议先在测试环境中按本文步骤完成端到端的接口验证，确认数据流转无误后再上线至生产环境。

准备好开始集成了吗？前往项目管理后台创建您的第一个HEXACO-JP API项目，亲自验证六大人格维度数据如何在您的系统中流转并转化为有价值的用户洞察。