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

HEXACO-JP API文档｜3步集成REST API获取诊断结果

本文将详细介绍HEXACO-JP API接口文档的完整集成流程与端点规范，帮助开发者将专业人格测评能力无缝嵌入自有服务。无论您是HR科技平台、职业发展应用还是企业内训系统，只需按照以下5个步骤，即可通过REST API集成获取用户的HEXACO六维人格评分、细项因子及行为倾向数据。

在正式开始之前，请确认您已在诊断站点完成项目创建并购买了回答配额。交互式OpenAPI规范文档（Swagger UI）也可在此处查阅，方便开发者在线调试每个API端点。

整体集成流程概览

理解整体架构是成功完成REST API集成的第一步。HEXACO-JP API采用”重定向-回调”模式，将测评界面托管于第三方服务器，同时通过标准化的查询参数将结果元数据安全地返回给接入方。整个流程共分为5个环节，研究表明这种无状态的OAuth风格设计能够显著降低敏感数据泄露风险。

  1. 在诊断站点创建项目，获取项目密钥、API密钥及重定向URL
  2. 将目标用户从自有服务重定向至HEXACO-JP答题页面
  3. 用户完成约100道题目并提交（约需10分钟）
  4. 提交完成后，用户携带查询参数（含responseId等）跳回您指定的重定向URL
  5. 服务端利用查询参数调用REST API，获取完整诊断结果

需要特别注意的是，API密钥绝对不能暴露在浏览器端（客户端），所有API调用必须经由您自己的服务器发起，这是保障数据安全的基本要求。

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

项目密钥与API密钥是整个人格测评接口调用链路的安全凭证，务必妥善保管。登录诊断站点后，在菜单中选择”商业使用”，按提示创建新项目。创建时需配置以下4个关键参数：

  • 项目类型：选择”API”模式，以启用REST API集成功能
  • 重定向URL：用户提交答卷后将跳转至您指定的站点URL，支持后续修改
  • 回答配额：预购本项目可消耗的答卷次数，每次费用为5美元（含税价格请参阅服务页面）
  • 题目内容：固定为HEXACO-JP 100题标准版，预计用时约10分钟

项目创建完成后，在项目详情页面将自动生成项目密钥（Project Key）和API密钥（JWT格式）。两者均可按需重新生成，重定向URL也可随时编辑，灵活适应不同业务场景。

STEP 2 & 3：引导用户完成测评

将用户引导至HEXACO-JP测评页面只需一个带参数的URL跳转，实现成本极低。在您的服务中，通过按钮或链接将用户重定向至以下地址：

https://personalities.me/biz/survey?token=<project_key>&sessionData=<session_data>
  • token：填入项目详情页面的项目密钥
  • sessionData：您自定义的用于唯一标识用户的URL编码字符串（例如用户邮箱地址）。该值在答卷完成后会原样附加到回调URL中，供您在服务端识别对应用户

用户进入答题页面后，将完成HEXACO-JP 100道标准题目（约10分钟），随后点击提交按钮。答卷数据的服务端存储与评分计算全部由Sunblaze平台负责处理，接入方无需自行实现评分逻辑。

STEP 4：接收回调并解析查询参数

提交完成后，系统会将用户重定向回您预设的URL，并在查询参数中携带后续API调用所需的全部元数据。您的服务端需要从这些参数中提取关键ID，用于下一步的诊断结果获取。回调参数共包含以下5个字段：

  • projectId（GUID格式）：当前项目的唯一标识符
  • surveyType（字符串，例如：hexaco-jp100）：问卷类型标识
  • responseId（GUID格式）：本次答卷的唯一标识符，API端点规范中最核心的参数
  • 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端点，您可以获取完整的HEXACO六维人格评分、24个细项因子以及行为倾向数据。从您的服务端发起GET请求，将回调参数嵌入路径中，并在请求头中以Bearer格式携带API密钥（JWT）。

API端点规范

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

Authorization: Bearer <api_key>

再次强调：API密钥不得在浏览器端（前端JS）中使用，必须始终由您的后端服务器代为发起请求，以防止密钥泄露。以下是一个使用curl的实现示例：

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}"

scope参数说明：WORK_ONLY与FULL的区别

API响应格式中，scope字段决定了返回数据的丰富程度。项目签约的scope不同，tendencies（行为倾向）的项目数量以及necessities（内在需求层级）字段的有无也会有所差异：

  • WORK_ONLY（标准版）：仅返回与工作、职业发展、团队协作相关的约80项行为倾向（包括darkTrend、highIQ、leadershipTransformational等），不含necessities字段。适合大多数HR和招聘场景
  • FULL（完整版）：返回约90项行为倾向的完整集合，同时包含necessities字段——对应马斯洛需求层级理论的内在需求倾向评分。适合需要深度人格洞察的应用场景

API响应格式示例（200 OK）

以下是标准的诊断结果获取响应结构，各字段含义如下：

{
  "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,
  "scope": "WORK_ONLY",
  "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": {
    "leadershipTransformational": 72,
    "goodTeam": 85
  }
}

各主要字段说明如下：

  • status："completed"表示答卷已完成，"in_progress"表示尚未完成。未完成时，completedAt与durationSeconds字段将返回null
  • scores：HEXACO六大维度的得分（value）及与母群体均值（average）的比较，可直接用于可视化展示
  • facets：HEXACO六维之下的24个细项因子评分（如诚实性、公正性等）
  • tendencies：与工作场景和性格特质相关联的行为倾向百分位分数，项目数量因scope不同而有约80至90项的差异
  • necessities：仅在scope=FULL时返回，反映马斯洛需求层级对应的内在驱动倾向评分

HTTP状态码说明

以下是调用API时可能返回的各类状态码及其含义，建议在服务端实现完整的错误处理逻辑：

  • 200 OK：请求成功，响应体中包含完整的诊断结果
  • 400 Bad Request：路径参数与API密钥所关联的项目不匹配。常见原因包括：projectId与密钥对应项目不符、responseId不属于该项目、surveyType与路径不一致、userId与路径不符，或答卷尚未提交完成
  • 401 Unauthorized：API密钥无效，或请求头中未指定Authorization: Bearer字段
  • 403 Forbidden：项目合约已失效或配额已耗尽
  • 404 Not Found：指定的responseId对应的答卷记录不存在

常见问题解答

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

请立即登录诊断站点，进入项目详情页面，分别点击”重新生成API密钥”或”重新生成项目密钥”按钮。旧密钥将立即失效，新密钥即时生效。建议在更新密钥后，同步更新服务端的环境变量配置，以避免服务中断。密钥管理应遵循最小权限原则，不应将其硬编码于代码仓库中。

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

可以。您可以随时在项目详情页面的重定向URL栏中进行更新，修改后对该项目下所有已发行的回答配额均立即生效。这意味着即使您的回调接口地址发生变更，也无需重新创建项目或重新购买配额，只需更新URL即可。建议在正式上线前充分测试回调接收逻辑。

回答配额是什么时候扣费的？

回答配额在项目创建时一次性预付，每次消耗费用为5美元（不含税）。配额在用户成功提交答卷后自动扣减。详细计费说明及套餐选项请参阅HEXACO-JP API服务介绍页面。建议根据预期用量提前购买足够配额，以避免因配额耗尽导致用户无法完成测评。

scope参数可以中途切换吗？

可以。WORK_ONLY和FULL两种scope均可按项目单位进行切换。如需变更，请通过联系表单提交申请。需要注意的是，scope切换通常影响后续新增答卷的返回内容，建议在切换前确认业务侧的数据解析逻辑是否已兼容FULL模式下的necessities字段。

sessionData参数有什么限制？

sessionData是由接入方自定义的任意字符串，用于在回调时识别对应用户，常见用法包括传入用户邮箱、内部用户ID或加密令牌。该值需进行URL编码（URL Encode），长度建议控制在合理范围内（通常不超过500个字符）。平台会在回调时将其原样附加到重定向URL的查询参数中，不做任何修改或解析。

用户答题中途退出会怎样？

如果用户在完成所有题目之前关闭了答题页面，则该次答卷的status将为"in_progress"，此时API端点将返回400 Bad Request错误（因答卷尚未完成）。completedAt和durationSeconds字段也将返回null。建议在您的回调处理逻辑中加入对此状态的判断，并引导用户重新参与测评。

在哪里可以查看交互式API文档？

HEXACO-JP API提供基于OpenAPI规范的交互式Swagger UI文档，访问地址为psych.sunblaze.jp/api/psych/api/docs。在该页面您可以直接在线测试各个API端点，查看请求参数、响应结构及状态码说明，是开发调试阶段的重要参考资源。

总结与相关资源

通过本文介绍的5个步骤，您可以将HEXACO-JP专业人格测评能力完整地集成至自有服务中：从项目创建、用户重定向、答卷回调，到最终通过HEXACO-JP API接口文档中定义的REST端点获取包含六维评分、24个细项因子及约80至90项行为倾向在内的完整诊断数据。整个集成流程设计清晰，开发者通常可在数小时内完成对接。如果您正在评估是否适合将该API引入您的平台，建议先访问服务介绍页面了解详细套餐与pricing信息，或前往Swagger UI在线浏览完整的端点规范，再结合您的业务场景决定最适合的scope配置——看看HEXACO数据能为您的用户带来哪些真实可用的人格洞察。